@africanies/angular-web-sdk 0.1.3 → 0.1.5

package/.nx/cache/9040451482998546630/dist/libs/africanies-core/types/africanies-africanies-core.d.ts

@@ -0,0 +1,2741 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, EnvironmentProviders, Signal, Type } from '@angular/core';
+import { HttpContextToken, HttpContext, HttpInterceptorFn, HttpFeature, HttpFeatureKind } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { ApiResponseModel, ShippingMode, PaginationQueryParamsModel, ApiJsonValue, PaginationMetaModel, ResourceId, ApiErrorDetailModel, ModeConfigDataModel, ModeRegionConfigModel, ModeAppType, CountryModel, CountryStateModel, DocumentModel, PlanModel, PlanPackageModel, ServiceModel, CurrencyModel, CurrencyPaymentMethodModel, CurrencyPaymentMethodPivotModel, CurrencyCreateRequestModel, CurrencyFlag01, CurrencyDeleteRequestModel, CurrencyUpdateRequestModel, PaymentMethodModel, PaymentMethodCurrencyModel, PaymentMethodFlag01, PaymentMethodUpdateRequestModel, ShipmentMethodModel, ShipmentMethodZoneLinkModel, ShipmentMethodZonePageModel, ShipmentZoneModel, WarehouseModel, WarehouseStateModel, ZoneModel, UserModel, UserAccountManagerModel, UserBusinessAccountModel, UserCountryModel, UserStateModel, UserGatewayPayloadModel, UserPaymentPayloadModel, UserPlanModel, UserPlanPackageModel, UserSubscriptionModel, ChangePasswordRequestModel, NotificationModel, NotificationInboxItemModel, NotificationPayloadModel, FileReadModel, FileReadRequestModel, ProductModel, ModuleFilterConfigModel, FilterOptionsSource, FilterFieldModel } from '@africanies/africanies-models';
+
+/**
+ * Per-request toast flags for {@link httpToastInterceptor}.
+ *
+ * Attach with {@link withToast}. When the token is absent, the interceptor
+ * stays quiet — toasting is opt-in per call.
+ */
+interface ToastHttpOptions {
+    /** Show a success toast when the response is OK. Default `true`. */
+    success: boolean;
+    /** Show an error toast when the request fails. Default `true`. */
+    error: boolean;
+    /** Override the default success copy. */
+    successMessage?: string;
+    /** Override the default error copy. */
+    errorMessage?: string;
+}
+/**
+ * Optional bridge from HTTP → toast UI.
+ *
+ * Provided by `@africanies/africanies-ui` {@link provideAfricaniesToasts}. When missing,
+ * {@link httpToastInterceptor} is a no-op even if {@link withToast} is set.
+ */
+interface AfricaniesHttpToastHandler {
+    /** Timed success toast. */
+    success(message: string): void;
+    /** Persistent error toast (user must dismiss). */
+    error(message: string): void;
+}
+/** DI token for the HTTP → toast bridge. */
+declare const AFRICANIES_HTTP_TOAST: InjectionToken<AfricaniesHttpToastHandler>;
+/**
+ * Present only when the request was tagged with {@link withToast}.
+ * Sentinel `null` means “not tagged”.
+ */
+declare const TOAST_HTTP_OPTIONS: HttpContextToken<ToastHttpOptions | null>;
+/**
+ * Opt a request into HTTP toasts.
+ *
+ * Defaults: `success: true`, `error: true`. Pass flags to silence either side.
+ *
+ * @param options - Partial overrides for the defaults.
+ * @returns HttpContext ready to pass as `context` on HttpClient calls.
+ *
+ * @example
+ * ```ts
+ * // Success + error toasts
+ * this.http.post(url, body, { context: withToast() });
+ *
+ * // Errors only
+ * this.http.post(url, body, { context: withToast({ success: false }) });
+ *
+ * // Custom copy
+ * this.http.post(url, body, {
+ *   context: withToast({
+ *     successMessage: 'Shipment saved',
+ *     errorMessage: 'Could not save shipment',
+ *   }),
+ * });
+ * ```
+ */
+declare function withToast(options?: Partial<ToastHttpOptions>): HttpContext;
+
+/**
+ * Default HTTP toast behaviour for {@link ApiClient} requests.
+ *
+ * - `'off'` (default) — no automatic tagging; use {@link withToast} on raw
+ *   HttpClient calls or {@link ApiRequestOptions.toast} per SDK call.
+ * - `'errors'` — tag mutating SDK requests (POST / PUT / PATCH / DELETE) with
+ *   error toasts only. GET stays silent so list/detail screens own their empty
+ *   / error UI.
+ * - `'all'` — success + error toasts on mutating SDK requests (GET still silent
+ *   unless the call opts in).
+ * - Partial {@link ToastHttpOptions} — custom defaults merged per mutating request.
+ */
+type AfricaniesSdkHttpToasts = 'off' | 'errors' | 'all' | Partial<ToastHttpOptions>;
+/**
+ * Runtime configuration for the AFRICANIES SDK HTTP layer and related services.
+ *
+ * Provided once at bootstrap via {@link provideAfricaniesSdk} and injected
+ * wherever the SDK needs the API origin or shared request defaults.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
+ * import { provideAfricaniesSdk, provideAfricaniesHttpClient } from '@africanies/africanies-core';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideZoneChangeDetection({ eventCoalescing: true }),
+ *     provideAfricaniesSdk({
+ *       baseUrl: 'https://api.example.com',
+ *       timeout: 30_000,
+ *       defaultHeaders: { 'X-App': 'stn-web' },
+ *     }),
+ *     provideAfricaniesHttpClient(),
+ *   ],
+ * };
+ * ```
+ */
+interface AfricaniesSdkConfig {
+    /**
+     * Absolute API origin used to resolve relative paths in {@link ApiClient}
+     * (e.g. `'https://api.example.com'`). Trailing slashes are trimmed when
+     * composing URLs so callers can pass either style.
+     */
+    baseUrl: string;
+    /**
+     * Per-request timeout in milliseconds applied by {@link ApiClient}.
+     * Omitted when the consumer prefers HttpClient / browser defaults only.
+     */
+    timeout?: number;
+    /**
+     * Headers merged onto every {@link ApiClient} request.
+     * Request-specific headers override these on key collision.
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * When true (default), fetch `/public/mode/config` on startup via
+     * {@link provideModeConfig}. Set `false` for tests or offline-only shells.
+     */
+    loadModeConfig?: boolean;
+    /**
+     * Automatic {@link withToast} tagging for {@link ApiClient} HTTP calls.
+     *
+     * Defaults to `'off'` so production apps opt in explicitly. Admin shells use
+     * `'errors'` so POST / PUT / PATCH / DELETE failures surface while GET list
+     * failures stay in-page.
+     */
+    httpToasts?: AfricaniesSdkHttpToasts;
+}
+/**
+ * DI token for the active {@link AfricaniesSdkConfig}.
+ *
+ * Apps must call {@link provideAfricaniesSdk} at bootstrap; injecting without that
+ * provider throws so misconfiguration fails fast rather than silently using
+ * an empty base URL.
+ */
+declare const AFRICANIES_SDK_CONFIG: InjectionToken<AfricaniesSdkConfig>;
+
+/**
+ * Registers SDK configuration and ensures browser storage is available.
+ *
+ * Also calls {@link provideLocalStorage} so theme / mode-config / auth-token
+ * persistence works out of the box. {@link ShippingModeService} always uses
+ * {@link SessionStorageService} so each tab can hold its own STN/SFN mode.
+ * When {@link AfricaniesSdkConfig.loadModeConfig} is not `false`, {@link provideModeConfig}
+ * runs on startup.
+ *
+ * @param config - API origin and optional timeout / default headers.
+ * @returns Environment providers for `app.config.ts`.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * import { ApplicationConfig } from '@angular/core';
+ * import {
+ *   provideAfricaniesSdk,
+ *   provideAfricaniesHttpClient,
+ * } from '@africanies/africanies-core';
+ * import { provideSessionStorage } from '@africanies/africanies-storage';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideAfricaniesSdk({
+ *       baseUrl: import.meta.env['NG_APP_API_URL'],
+ *       timeout: 30_000,
+ *     }),
+ *     // Optional: override the localStorage default registered above
+ *     // provideSessionStorage(),
+ *     provideAfricaniesHttpClient(),
+ *     // Or with app interceptors:
+ *     // provideAfricaniesHttpClient({ interceptors: [loggingInterceptor] }),
+ *   ],
+ * };
+ * ```
+ */
+declare function provideAfricaniesSdk(config: AfricaniesSdkConfig): EnvironmentProviders;
+
+/** Forgot-password path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const AUTH_FORGOT_PASSWORD_PATH = "/auth/forgot/password";
+
+/**
+ * Unauthenticated auth endpoints (`POST /auth/…`).
+ *
+ * **Forgot password is email-only.** `forgot()` POSTs `{ email }`; the
+ * backend emails a reset link. This product UI never collects a new password
+ * for that link (no token in the route, `/onboarding/reset-password` is
+ * **not** that flow).
+ *
+ * `/onboarding/reset-password` is first login with a default password: after
+ * login, if `user.default_password` is set, the host sends the user there to
+ * change current → new via {@link UserService.changePassword}.
+ *
+ * Token persistence stays on {@link AuthTokenService}. These calls do not
+ * require a bearer token — the interceptor omits `Authorization` when none
+ * is stored. Admin user/partner screens reuse {@link forgot} with that
+ * user’s email.
+ *
+ * @example
+ * ```ts
+ * const authApi = inject(AuthService);
+ *
+ * authApi.forgot('user@example.com').subscribe((res) => {
+ *   if (res.success) {
+ *     // Show res.message, then “Reset completed? Login here”.
+ *   }
+ * });
+ * ```
+ */
+declare class AuthService {
+    private readonly api;
+    /**
+     * Request a password-reset email (`POST /auth/forgot/password`).
+     *
+     * Enable submit only when the address looks valid. Wire `data` is an empty
+     * array on success — use {@link ApiResponseModel.message} for the banner.
+     *
+     * @param email - Registered account email.
+     * @returns Normalized envelope (`data` is typically `[]`).
+     */
+    forgot(email: string): Observable<ApiResponseModel<unknown[]>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AuthService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AuthService>;
+}
+
+/**
+ * Holds the bearer access token used by {@link authInterceptor}.
+ *
+ * After login/register in the host app, call {@link set}. The SDK persists the
+ * token via {@link STORAGE_TOKEN} and attaches `Authorization: Bearer …` on
+ * outbound HTTP. On logout, call {@link UserService.logoutFromAllSessions}
+ * while the token is still set, then {@link clear} (also clears the GET cache).
+ *
+ * @example
+ * ```ts
+ * const auth = inject(AuthTokenService);
+ * const users = inject(UserService);
+ *
+ * // after login
+ * auth.set(res.access_token);
+ *
+ * // later — UserService.me() is authenticated automatically
+ * // on logout — POST while the token is still set, then drop it
+ * users.logoutFromAllSessions().subscribe({
+ *   next: () => auth.clear(),
+ *   error: () => auth.clear(),
+ * });
+ * ```
+ */
+declare class AuthTokenService {
+    private readonly storage;
+    private readonly api;
+    private readonly _token;
+    /** Read-only view of the current access token. */
+    readonly token: Signal<string | null>;
+    /**
+     * Current access token, or `null` when logged out / unset.
+     */
+    get(): string | null;
+    /**
+     * Persist and activate an access token from login/register.
+     *
+     * @param accessToken - Bearer token string (whitespace-only is treated as clear).
+     */
+    set(accessToken: string): void;
+    /**
+     * Remove the token from memory and storage, and clear the HTTP GET cache.
+     */
+    clear(): void;
+    private readInitialToken;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AuthTokenService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AuthTokenService>;
+}
+
+/**
+ * Enable forgot-password submit when the address looks like an email.
+ *
+ * Intentionally loose (`local@host.tld`) — the API owns uniqueness and
+ * deliverability. Empty / whitespace-only values fail.
+ *
+ * @param value - Raw field value.
+ * @returns Whether submit should be enabled.
+ */
+declare function isValidEmail(value: unknown): boolean;
+
+/**
+ * Attaches the current shipping mode as an `x-shipment-mode` header.
+ *
+ * Uses {@link SHIPPING_MODE_OVERRIDE} when the request was tagged (via
+ * {@link ApiRequestOptions.shippingMode} or {@link withShippingMode});
+ * otherwise {@link ShippingModeService.mode}. The tab mode is never mutated.
+ *
+ * Some backends also expect `mode` as a query param (see {@link ApiClient.getResource});
+ * this interceptor covers the header half so domain calls stay consistent
+ * without each service remembering the header name.
+ *
+ * Prefer {@link provideAfricaniesHttpClient}, which registers this interceptor by
+ * default. {@link ShippingModeService} is `providedIn: 'root'` and needs no
+ * extra provider.
+ *
+ * @param req - Outgoing request.
+ * @param next - Next handler in the interceptor chain.
+ * @returns The downstream observable for the cloned request.
+ * @example
+ * ```ts
+ * provideAfricaniesSdk({ baseUrl: 'https://api.example.com' }),
+ * provideAfricaniesHttpClient(),
+ *
+ * api.post('/claim', body, { shippingMode: 'stn' });
+ * ```
+ */
+declare const shipmentModeInterceptor: HttpInterceptorFn;
+
+/**
+ * Per-request shipping-mode override for {@link shipmentModeInterceptor}.
+ *
+ * When set, `x-shipment-mode` uses this value instead of
+ * {@link ShippingModeService.mode}. The tab / session mode is unchanged.
+ * Sentinel `null` means “use the active tab mode”.
+ */
+declare const SHIPPING_MODE_OVERRIDE: HttpContextToken<ShippingMode | null>;
+/**
+ * Narrow unknown JSON / option values to a {@link ShippingMode}.
+ *
+ * @param value - Candidate value.
+ * @returns `'stn'` or `'sfn'` when valid; otherwise `undefined`.
+ */
+declare function asShippingMode(value: unknown): ShippingMode | undefined;
+/**
+ * Tag a request so {@link shipmentModeInterceptor} sends a different
+ * `x-shipment-mode` without calling {@link ShippingModeService.setMode}.
+ *
+ * Prefer {@link ApiRequestOptions.shippingMode} on {@link ApiClient} calls.
+ * Use this helper with raw `HttpClient`.
+ *
+ * @param mode - Mode for this request only.
+ * @param context - Existing context to merge (e.g. from {@link withToast}).
+ * @returns HttpContext with the override set.
+ *
+ * @example
+ * ```ts
+ * this.http.post(url, body, { context: withShippingMode('stn') });
+ * ```
+ */
+declare function withShippingMode(mode: ShippingMode, context?: HttpContext): HttpContext;
+
+/**
+ * Optional gate before a shell mode switch applies.
+ *
+ * Return `true` to allow {@link ShippingModeService.requestModeChange} to
+ * persist the new mode; `false` keeps the current mode.
+ */
+type ShippingModeChangeGuard = (next: ShippingMode, current: ShippingMode) => Observable<boolean>;
+/**
+ * Signal-based holder for the active {@link ShippingMode}.
+ *
+ * Persists through {@link SessionStorageService} under
+ * {@link AFRICANIES_SHIPPING_MODE_KEY} so each browser tab can hold its own STN/SFN
+ * context (refresh within the tab keeps the choice; other tabs are unaffected).
+ * Defaults to `'sfn'` when nothing is stored or the stored value is not a known
+ * mode — preferring a safe outbound default over failing open on corrupt storage.
+ *
+ * Changing mode clears {@link ApiClient}'s GET cache so `readAll` / by-id
+ * dumps cannot cross STN↔SFN (cache keys omit the mode header). `ApiClient`
+ * is resolved lazily via {@link Injector} to avoid a DI cycle.
+ *
+ * List screens should drop in-memory rows and show a blocking loader until
+ * the new mode's page arrives — STN rows must not linger on SFN. Use
+ * `listFetchKind` with `reason: 'mode'`.
+ *
+ * Features that must warn before a switch (e.g. mid Create Shipment) can
+ * {@link registerModeChangeGuard}. The shell switch uses
+ * {@link requestModeChange}; programmatic {@link setMode} bypasses the guard.
+ *
+ * Provided in root; no explicit provider registration is required.
+ * Pair with {@link shipmentModeInterceptor} so HTTP calls advertise the mode.
+ *
+ * @example
+ * ```ts
+ * const shipping = inject(ShippingModeService);
+ * shipping.setMode('stn');
+ * console.log(shipping.mode()); // 'stn'
+ * ```
+ */
+declare class ShippingModeService {
+    private readonly storage;
+    private readonly injector;
+    private readonly _mode;
+    private modeChangeGuard;
+    /**
+     * Read-only view of the current shipping mode (`Signal` = Angular's
+     * readonly signal surface; mutate only via {@link setMode} /
+     * {@link requestModeChange}).
+     */
+    readonly mode: Signal<ShippingMode>;
+    /**
+     * Register a single guard for shell mode switches. Pass `null` to clear
+     * (e.g. on feature destroy). Only one guard is active at a time.
+     * @param guard
+     */
+    registerModeChangeGuard(guard: ShippingModeChangeGuard | null): void;
+    /**
+     * Shell switch entry point: runs any registered guard, then applies the
+     * mode when allowed.
+     *
+     * @param mode - `'stn'` or `'sfn'`.
+     * @returns Emits once with `true` when the mode changed, else `false`.
+     */
+    requestModeChange(mode: ShippingMode): Observable<boolean>;
+    /**
+     * Updates the active mode and persists it for the current tab.
+     * No-ops when `mode` already matches the current value.
+     * Bypasses {@link registerModeChangeGuard} — prefer
+     * {@link requestModeChange} for user-driven switches.
+     *
+     * @param mode - `'stn'` or `'sfn'`.
+     */
+    setMode(mode: ShippingMode): void;
+    private applyMode;
+    private readInitialMode;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ShippingModeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ShippingModeService>;
+}
+
+/**
+ * Shared request options for {@link ApiClient} verbs.
+ *
+ * ## In-memory GET caching (`cacheTtlMs`)
+ *
+ * Optional short-TTL cache for identical GET URLs. See {@link HttpResponseCache}
+ * for when **not** to enable it (volatile data, auth-sensitive payloads,
+ * post-mutation lists). Prefer TanStack Query for app-level caching.
+ */
+interface ApiRequestOptions {
+    /**
+     * `'wrapped'` (default) → {@link ApiResponseModel}; `'raw'` → payload `T`.
+     * Both paths still run through {@link normalize} so null-safety is consistent.
+     */
+    responseMode?: 'wrapped' | 'raw';
+    /** Extra headers; override {@link AfricaniesSdkConfig.defaultHeaders} on conflict. */
+    headers?: Record<string, string>;
+    /** Query string values; `null` / `undefined` / `''` entries are omitted. */
+    params?: Record<string, string | number | boolean | null | undefined>;
+    /**
+     * When set on GET, serve/store the normalized result in the in-memory cache
+     * for this many milliseconds. Omit for uncached reads (the common case).
+     */
+    cacheTtlMs?: number;
+    /**
+     * HTTP toast tagging for this request (via {@link httpToastInterceptor}).
+     *
+     * - Omitted — use {@link AfricaniesSdkConfig.httpToasts} when set (mutations only;
+     *   GET stays silent unless you opt in here).
+     * - `false` — never toast this call (overrides config). Prefer only for rare
+     *   cases that fully own error UI; mutations should usually toast.
+     * - Partial flags — merge with config defaults (same shape as {@link withToast}).
+     */
+    toast?: Partial<ToastHttpOptions> | false;
+    /**
+     * Override `x-shipment-mode` for this request only.
+     *
+     * Does not call {@link ShippingModeService.setMode} — the tab / session mode
+     * stays unchanged. {@link getResource} also uses this for the `mode` query
+     * param when provided.
+     */
+    shippingMode?: ShippingMode;
+}
+/**
+ * Endpoint-agnostic HTTP façade over Angular {@link HttpClient}.
+ *
+ * Domain services own path strings — this client never hard-codes product
+ * routes (except helpers like {@link getResource} that only know conventions).
+ *
+ * Features:
+ * - `responseMode` overloads (`wrapped` | `raw`)
+ * - {@link normalize} on every **2xx** body
+ * - HTTP failures rethrown as `Error` whose `.message` is already
+ *   user-facing ({@link formatApiErrorMessage}) — consumers do not need to
+ *   parse `HttpErrorResponse` bodies
+ * - **No automatic retry** — fail fast so UIs can show Select / table /
+ *   error-state Retry instead of a stuck loading spinner
+ * - Optional per-GET TTL cache via `cacheTtlMs`
+ *
+ * @example
+ * ```ts
+ * const api = inject(ApiClient);
+ * api.get<User>('/users/1').subscribe({
+ *   next: (res) => {
+ *     if (res.success) console.log(res.data);
+ *     else console.error(res.message); // already joined when a validation bag exists
+ *   },
+ *   error: (err: Error) => console.error(err.message),
+ * });
+ * ```
+ */
+declare class ApiClient {
+    private readonly http;
+    private readonly config;
+    private readonly shippingMode;
+    private readonly cache;
+    /**
+     * GET with wrapped {@link ApiResponseModel} (default).
+     *
+     * @typeParam T - Payload type inside `data`.
+     */
+    get<T>(path: string, options?: ApiRequestOptions & {
+        responseMode?: 'wrapped';
+    }): Observable<ApiResponseModel<T>>;
+    /**
+     * GET returning the bare payload type (after normalize + unwrap).
+     *
+     * @typeParam T - Unwrapped payload type.
+     */
+    get<T>(path: string, options: ApiRequestOptions & {
+        responseMode: 'raw';
+    }): Observable<T>;
+    /**
+     * POST with wrapped envelope (default).
+     *
+     * @typeParam T - Payload type inside `data`.
+     * @typeParam TBody - JSON body type.
+     */
+    post<T, TBody = unknown>(path: string, body: TBody, options?: ApiRequestOptions & {
+        responseMode?: 'wrapped';
+    }): Observable<ApiResponseModel<T>>;
+    /**
+     * POST returning bare payload `T`.
+     *
+     * @typeParam T - Unwrapped payload type.
+     * @typeParam TBody - JSON body type.
+     */
+    post<T, TBody = unknown>(path: string, body: TBody, options: ApiRequestOptions & {
+        responseMode: 'raw';
+    }): Observable<T>;
+    /**
+     * PATCH with wrapped envelope (default).
+     *
+     * @typeParam T - Payload type inside `data`.
+     * @typeParam TBody - JSON body type.
+     */
+    patch<T, TBody = unknown>(path: string, body: TBody, options?: ApiRequestOptions & {
+        responseMode?: 'wrapped';
+    }): Observable<ApiResponseModel<T>>;
+    /**
+     * PATCH returning bare payload `T`.
+     *
+     * @typeParam T - Unwrapped payload type.
+     * @typeParam TBody - JSON body type.
+     */
+    patch<T, TBody = unknown>(path: string, body: TBody, options: ApiRequestOptions & {
+        responseMode: 'raw';
+    }): Observable<T>;
+    /**
+     * PUT with wrapped envelope (default).
+     *
+     * @typeParam T - Payload type inside `data`.
+     * @typeParam TBody - JSON body type.
+     */
+    put<T, TBody = unknown>(path: string, body: TBody, options?: ApiRequestOptions & {
+        responseMode?: 'wrapped';
+    }): Observable<ApiResponseModel<T>>;
+    /**
+     * PUT returning bare payload `T`.
+     *
+     * @typeParam T - Unwrapped payload type.
+     * @typeParam TBody - JSON body type.
+     */
+    put<T, TBody = unknown>(path: string, body: TBody, options: ApiRequestOptions & {
+        responseMode: 'raw';
+    }): Observable<T>;
+    /**
+     * DELETE with wrapped envelope (default).
+     *
+     * @typeParam T - Payload type inside `data`.
+     * @typeParam TBody - Optional JSON body (Laravel deletes that expect `{ id }`).
+     */
+    delete<T, TBody = unknown>(path: string, body?: TBody, options?: ApiRequestOptions & {
+        responseMode?: 'wrapped';
+    }): Observable<ApiResponseModel<T>>;
+    /**
+     * DELETE returning bare payload `T`.
+     *
+     * @typeParam T - Unwrapped payload type.
+     * @typeParam TBody - Optional JSON body.
+     */
+    delete<T, TBody = unknown>(path: string, body: TBody | undefined, options: ApiRequestOptions & {
+        responseMode: 'raw';
+    }): Observable<T>;
+    /**
+     * List/detail GET using the AFRICANIES {@link ResourceId} convention.
+     *
+     * Prefer the named helpers when exploring the API in the IDE:
+     * - {@link getResourcePage} — `id: null` (paginated)
+     * - {@link getResourceAll} — `id: 'all'`
+     * - {@link getResourceById} — numeric id
+     *
+     * Always attaches `mode` from the active tab or {@link ApiRequestOptions.shippingMode}
+     * (in addition to the `x-shipment-mode` header from {@link shipmentModeInterceptor}).
+     *
+     * @typeParam T - Element type for lists, or record type for by-id.
+     *
+     * @example
+     * ```ts
+     * api.getResource<Shipment>('shipments', null, { page: 1, size: 15 })
+     *   .subscribe((res) => console.log(res.data, res.pagination));
+     * ```
+     */
+    getResource<T>(basePath: string, id: null, query?: PaginationQueryParamsModel, options?: ApiRequestOptions): Observable<ApiResponseModel<T[]>>;
+    /**
+     * Full unpaginated list: `GET {basePath}/all` (pagination query ignored).
+     *
+     * @typeParam T - Element type of the list.
+     */
+    getResource<T>(basePath: string, id: 'all', query?: PaginationQueryParamsModel, options?: ApiRequestOptions): Observable<ApiResponseModel<T[]>>;
+    /**
+     * Single record: `GET {basePath}/{id}` (pagination query ignored).
+     *
+     * @typeParam T - Record type.
+     */
+    getResource<T>(basePath: string, id: number, query?: PaginationQueryParamsModel, options?: ApiRequestOptions): Observable<ApiResponseModel<T>>;
+    /**
+     * Paginated list — {@link ResourceId} `null`.
+     * IDE-friendly alias for `getResource(basePath, null, query)`.
+     *
+     * Page size defaults to {@link DEFAULT_PAGE_SIZE} (`15`) unless
+     * `query.size` is set. Bind `res.pagination` to `africanies-pagination`.
+     *
+     * @typeParam T - Element type of the list.
+     * @param basePath - Resource base path (no trailing id segment).
+     * @param query - Optional page/size/order.
+     */
+    getResourcePage<T>(basePath: string, query?: PaginationQueryParamsModel): Observable<ApiResponseModel<T[]>>;
+    /**
+     * Full unpaginated dump — {@link ResourceId} `'all'`.
+     * IDE-friendly alias for `getResource(basePath, 'all')`.
+     *
+     * @typeParam T - Element type of the list.
+     * @param basePath - Resource base path.
+     */
+    getResourceAll<T>(basePath: string): Observable<ApiResponseModel<T[]>>;
+    /**
+     * Single record — {@link ResourceId} number.
+     * IDE-friendly alias for `getResource(basePath, id)`.
+     *
+     * @typeParam T - Record type.
+     * @param basePath - Resource base path.
+     * @param id - Numeric primary key.
+     */
+    getResourceById<T>(basePath: string, id: number): Observable<ApiResponseModel<T>>;
+    /**
+     * Clears the in-memory GET cache (e.g. on logout).
+     */
+    clearCache(): void;
+    private buildHttpContext;
+    private request;
+    private unwrap;
+    private resolveUrl;
+    private buildHeaders;
+    private buildParams;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ApiClient, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ApiClient>;
+}
+
+/**
+ * Resolve user-facing error copy from an API envelope, raw body, or HttpClient error.
+ *
+ * Prefers joined field messages when present; otherwise envelope / HTTP `message`.
+ *
+ * Prefer relying on {@link ApiClient}: HTTP failures are already rethrown as
+ * `Error` with this text on `.message`. Hosts mainly need this helper when
+ * calling Angular `HttpClient` directly (e.g. toast interceptor).
+ *
+ * @param input - Normalized response, raw JSON body, or {@link HttpErrorResponse}.
+ */
+declare function formatApiErrorMessage(input: unknown): string;
+
+/**
+ * Functional interceptor that sets `Authorization: Bearer <token>` when
+ * {@link AuthTokenService} has an access token (from {@link AuthTokenService.set}).
+ *
+ * Compose via {@link provideAfricaniesHttpClient} (preferred) or pass explicitly to
+ * `provideHttpClient(withInterceptors([...]))`.
+ * @param req
+ * @param next
+ */
+declare const authInterceptor: HttpInterceptorFn;
+
+/**
+ * Tiny in-memory TTL cache for {@link ApiClient} GET responses.
+ *
+ * Intentionally process-local and non-persistent: it exists to skip identical
+ * GETs within a short window (e.g. rapid remounts), not to replace TanStack
+ * Query or server cache headers.
+ *
+ * ## When NOT to use caching (`cacheTtlMs`)
+ *
+ * - Frequently changing data (dashboards, live rates, inventory) — stale reads
+ *   are worse than an extra round-trip.
+ * - User-specific or permission-sensitive payloads — another user/session in
+ *   the same SPA tab could theoretically share the in-memory map.
+ * - After mutations that invalidate list/detail views — this cache has no
+ *   tag-based invalidation; prefer TanStack Query for that.
+ * - Large payloads — every entry stays in heap until TTL expiry.
+ *
+ * Prefer omitting `cacheTtlMs` unless you have a measured hot-spot and a
+ * known staleness budget.
+ */
+/**
+ * Key/value store with per-entry TTL eviction on read.
+ */
+declare class HttpResponseCache {
+    private readonly store;
+    /**
+     * Returns a cached value when present and not expired.
+     *
+     * @param key - Stable request identity (method + URL + relevant params).
+     * @returns The stored value, or `null` on miss / expiry.
+     */
+    get<T>(key: string): T | null;
+    /**
+     * Stores a value until `ttlMs` elapses.
+     *
+     * @param key - Stable request identity.
+     * @param value - Value to reuse for subsequent hits.
+     * @param ttlMs - Time-to-live in milliseconds from now.
+     */
+    set(key: string, value: unknown, ttlMs: number): void;
+    /**
+     * Drops every entry. Useful after logout or global invalidation hooks.
+     */
+    clear(): void;
+}
+
+/**
+ * Shows success / error toasts for requests tagged with {@link withToast}.
+ *
+ * Requires {@link AFRICANIES_HTTP_TOAST} (from `provideAfricaniesToasts` in `@africanies/africanies-ui`).
+ * Untagged requests never toast. Missing handler → silent no-op.
+ * @param req - Outgoing HTTP request.
+ * @param next - Next interceptor handler.
+ * @returns Observable for the HTTP response stream.
+ */
+declare const httpToastInterceptor: HttpInterceptorFn;
+
+/**
+ * Deep-map arbitrary JSON into {@link ApiJsonValue} with no `undefined`.
+ *
+ * - `undefined` / unsupported types → `null`
+ * - Arrays → every element mapped (never sparse/`undefined` slots)
+ * - Objects → every own key mapped to {@link ApiJsonValue}
+ *
+ * @param raw - Wire value (may be missing or malformed).
+ * @returns Null-safe JSON tree, or `null` when `raw` is nullish/unusable.
+ */
+declare function mapApiJsonValue(raw: unknown): ApiJsonValue | null;
+/**
+ * Map a wire list into a null-safe {@link ApiJsonValue} array.
+ * Non-arrays become `[]`.
+ * @param raw - Candidate list.
+ * @returns Mapped array (never null/undefined).
+ */
+declare function mapApiJsonList(raw: unknown): ApiJsonValue[];
+
+/**
+ * Map pagination from snake_case (preferred), legacy camelCase, or Laravel keys.
+ * @param value
+ */
+declare function normalizePagination(value: unknown): PaginationMetaModel | null;
+/**
+ * Flatten a Laravel paginator in `data` into list payload + {@link PaginationMetaModel}.
+ * @param raw
+ */
+declare function unwrapLaravelPaginator<T>(raw: unknown): {
+    data: T[] | null;
+    pagination: PaginationMetaModel | null;
+};
+/**
+ * Normalize any HTTP JSON body into a fully null-safe {@link ApiResponseModel}.
+ *
+ * Envelope fields use snake_case where the wire does (`status_code`,
+ * pagination keys). Paginated list reads often embed a Laravel paginator in
+ * `data` (`data.data` + totals) — that shape is flattened here so consumers
+ * always see `data: T[]` and `pagination`.
+ *
+ * Validation failures that return a Laravel field bag in `errors` or `data`
+ * are lifted into `errors: ApiErrorDetailModel[]`. On failure, a bag in
+ * `data` is cleared (`data: null`) so it is not typed as success payload `T`.
+ * Top-level `message` is enriched to the joined field messages when a bag
+ * exists (API `message` alone is often only the first field).
+ * @param raw
+ */
+declare function normalize<T>(raw: unknown): ApiResponseModel<T>;
+
+/**
+ * Options for {@link provideAfricaniesHttpClient}.
+ */
+interface AfricaniesHttpClientOptions {
+    /**
+     * Extra interceptors appended **after** the SDK defaults
+     * (`shipmentModeInterceptor`, `authInterceptor`, `httpToastInterceptor`).
+     */
+    interceptors?: HttpInterceptorFn[];
+}
+/**
+ * Registers `HttpClient` with AFRICANIES default interceptors baked in.
+ *
+ * Defaults (in order):
+ * 1. {@link shipmentModeInterceptor} — `x-shipment-mode`
+ * 2. {@link authInterceptor} — `Authorization` when {@link AuthTokenService} has a token
+ * 3. {@link httpToastInterceptor} — toasts for requests tagged with {@link withToast}
+ *    (no-op until `provideAfricaniesToasts()` registers {@link AFRICANIES_HTTP_TOAST})
+ * 4. Any {@link AfricaniesHttpClientOptions.interceptors} from the host
+ *
+ * @param options - Optional extra interceptors.
+ * @param features - Extra `provideHttpClient` features (`withFetch`, etc.).
+ * @returns Environment providers for `app.config.ts`.
+ *
+ * @example
+ * ```ts
+ * provideAfricaniesSdk({ baseUrl: 'https://api.example.com' }),
+ * provideAfricaniesHttpClient(),
+ * provideAfricaniesToasts(), // from @africanies/africanies-ui — enables HTTP toasts
+ * ```
+ */
+declare function provideAfricaniesHttpClient(options?: AfricaniesHttpClientOptions, ...features: HttpFeature<HttpFeatureKind>[]): EnvironmentProviders;
+
+/**
+ * Optional query bag for {@link ResourceId} GETs.
+ *
+ * `page` / `size` / `order` apply only when `id` is `null` (paginated list).
+ * Extra keys are always forwarded (filters, includes, etc.).
+ *
+ * App Settings list screens commonly send `search`, `from`, and `to` on the
+ * paginated read — use this type directly; do not invent per-domain
+ * `*ReadParams` aliases for the same bag.
+ */
+type ResourceQueryParams = PaginationQueryParamsModel & Record<string, string | number | boolean | null | undefined>;
+/**
+ * Build a path for the AFRICANIES list/detail `ResourceId` convention.
+ *
+ * | `id` | Path |
+ * |------|------|
+ * | `null` | `{basePath}` — paginated |
+ * | `'all'` | `{basePath}/all` — full list |
+ * | `number` | `{basePath}/{id}` — single record |
+ *
+ * @param basePath - Endpoint base (e.g. `/product/read`).
+ * @param id - {@link ResourceId}; defaults to `null` (paginated).
+ * @returns Absolute-or-relative path segment for {@link ApiClient.get}.
+ *
+ * @example
+ * ```ts
+ * buildResourcePath('/product/read')        // '/product/read'
+ * buildResourcePath('/product/read', 'all') // '/product/read/all'
+ * buildResourcePath('/product/read', 42)    // '/product/read/42'
+ * ```
+ */
+declare function buildResourcePath(basePath: string, id?: ResourceId): string;
+/**
+ * Build query params for a {@link ResourceId} request.
+ *
+ * Pagination fields (`page`, `size`, `order`) are included only when
+ * `id === null`. Other keys are always passed through.
+ *
+ * Paginated lists (`id === null`) always send `size`, defaulting to
+ * {@link DEFAULT_PAGE_SIZE} (`15`) when omitted.
+ *
+ * @param id - Active resource id mode.
+ * @param params - Optional pagination + filter bag.
+ * @returns Params object for {@link ApiClient}, or `undefined` when empty.
+ */
+declare function buildResourceQueryParams(id: ResourceId, params?: ResourceQueryParams): Record<string, string | number | boolean | null | undefined> | undefined;
+/**
+ * In-memory GET cache TTL for reference reads.
+ *
+ * Paginated lists (`id === null`) are never cached — page contents change.
+ * `'all'` and by-id may use a short TTL for stable catalogs.
+ *
+ * @param id - Active resource id mode.
+ * @param ttlMs - Desired TTL for stable reads.
+ * @returns TTL to pass to {@link ApiClient}, or `undefined` to skip cache.
+ */
+declare function resourceCacheTtlMs(id: ResourceId, ttlMs: number): number | undefined;
+/**
+ * Map wire `data` according to {@link ResourceId} shape.
+ *
+ * - `null` / `'all'` → list mapper → `T[]`
+ * - `number` → one mapper → `T` (first element if the wire sent an array)
+ *
+ * @typeParam T - Domain model type.
+ * @param id - Active resource id mode.
+ * @param raw - Envelope `data` payload.
+ * @param mapOne - Mapper for a single record.
+ * @param mapMany - Mapper for a list (or single object coerced to list).
+ * @returns Mapped payload, or `null` when by-id data is missing.
+ *          List reads (`null` / `'all'`) return `[]` when `raw` is nullish.
+ */
+declare function mapResourcePayload<T>(id: ResourceId, raw: unknown, mapOne: (raw: unknown) => T, mapMany: (raw: unknown) => T[]): T | T[] | null;
+
+/**
+ * Laravel-style validation bag: `{ field: ["msg", ...] }`.
+ * @param value - Candidate JSON object.
+ */
+declare function isLaravelValidationBag(value: unknown): boolean;
+/**
+ * Flatten a validation bag into {@link ApiErrorDetailModel} rows.
+ *
+ * Uses messages in order; the first message per field is what
+ * {@link fieldErrorsMap} exposes for form binding.
+ * @param bag - Field → messages map.
+ */
+declare function mapLaravelValidationBag(bag: Record<string, unknown>): ApiErrorDetailModel[];
+/**
+ * Join field errors for toast / banner copy (one line per message, de-duped).
+ * Prefer this over top-level `message` when a bag is present — the envelope
+ * `message` is often only the first field.
+ * @param errors - Normalized field errors.
+ */
+declare function joinApiErrorMessages(errors: ApiErrorDetailModel[] | null | undefined): string | null;
+/**
+ * First message per field for form control binding.
+ * @param errors - Normalized field errors.
+ */
+declare function fieldErrorsMap(errors: ApiErrorDetailModel[] | null | undefined): Record<string, string>;
+
+/**
+ * Null-safe coercions for AFRICANIES wire JSON.
+ *
+ * Mappers should run every request/response field through these helpers so
+ * missing keys, `null`, and wrong JSON types never throw at `.map` / `.trim`.
+ */
+/**
+ * Narrow unknown JSON into a plain object record.
+ * @param value - Candidate value.
+ * @returns Record when a non-array object; otherwise `null`.
+ */
+declare function asRecord(value: unknown): Record<string, unknown> | null;
+/**
+ * Coerce a value to an array. Non-arrays become `[]`.
+ * @param value - Candidate list.
+ */
+declare function asArray<T = unknown>(value: unknown): T[];
+/**
+ * Map every element of a wire list. Non-arrays yield `[]`.
+ * @param value - Candidate list.
+ * @param mapOne - Per-item mapper.
+ */
+declare function mapArray<T>(value: unknown, mapOne: (entry: unknown) => T): T[];
+/**
+ * Map a list-or-single payload (Laravel sometimes sends one object).
+ *
+ * - `null` / `undefined` → `[]`
+ * - paginator / `{ data | items }` → mapped inner rows
+ * - array → mapped items
+ * - anything else → one mapped item
+ *
+ * @param value - Envelope `data` (or a nested list field).
+ * @param mapOne - Per-item mapper.
+ */
+declare function mapList<T>(value: unknown, mapOne: (entry: unknown) => T): T[];
+/**
+ * Finite number, or `fallback` when missing/invalid.
+ * @param value - Raw numeric field.
+ * @param fallback - Default when not a finite number.
+ */
+declare function asNumber(value: unknown, fallback?: number): number;
+/**
+ * Finite number, or `null` when missing/invalid.
+ * @param value - Raw numeric field.
+ */
+declare function asNullableNumber(value: unknown): number | null;
+/**
+ * String, or `fallback` when the value cannot be stringified usefully.
+ * @param value - Raw string field.
+ * @param fallback - Default when nullish / non-scalar.
+ */
+declare function asString(value: unknown, fallback?: string): string;
+/**
+ * String or `null` (never `undefined`).
+ * @param value - Raw string field.
+ */
+declare function asNullableString(value: unknown): string | null;
+/**
+ * Boolean from wire flags (`true` / `false` / `1` / `0` / `"true"` / `"1"`).
+ * Missing values are `false`.
+ * @param value - Raw flag.
+ */
+declare function asBoolean(value: unknown): boolean;
+/**
+ * Boolean or `null` when the field is absent / unparseable.
+ * @param value - Raw flag.
+ */
+declare function asNullableBoolean(value: unknown): boolean | null;
+/**
+ * Wire `"1"` / `"0"` from a boolean, number, or string flag.
+ * @param value - Host or wire flag.
+ */
+declare function toFlag01(value: unknown): '0' | '1';
+/**
+ * User-model `0` / `1` flag, or `null` when absent.
+ * @param value - Raw flag.
+ */
+declare function asNullableFlag01(value: unknown): 0 | 1 | null;
+
+/**
+ * Why a list screen is fetching.
+ *
+ * - `initial` — first paint (no rows yet).
+ * - `focus` — tab/window became visible again.
+ * - `refresh` — toolbar Refresh.
+ * - `page` — pager page or size change.
+ * - `mode` — {@link ShippingModeService} switched STN ↔ SFN.
+ */
+type ListFetchReason = 'initial' | 'focus' | 'refresh' | 'page' | 'mode';
+/**
+ * How to bind the list table while that fetch is in flight.
+ *
+ * - `loading` — body spinner. Use when there is no data, or the shipping
+ *   mode changed (previous rows belong to the other mode — drop them).
+ * - `pagination` — keep rows; pager spinner.
+ * - `refreshing` — keep rows; refresh icon spins (focus / Refresh).
+ */
+type ListFetchKind = 'loading' | 'pagination' | 'refreshing';
+/**
+ * Pick blocking vs keep-rows fetch for a list table.
+ *
+ * Body loading only when there is no initial data or the shipping mode
+ * switched. Page/size keeps rows. Tab focus and Refresh keep rows.
+ *
+ * @param options
+ * @param options.hasData - Rows from the *current* mode are already on screen.
+ * @param options.reason - What triggered this fetch.
+ * @returns Kind to map onto `loading` / `pageLoading` / `refreshing`.
+ *
+ * @example
+ * ```ts
+ * const kind = listFetchKind({
+ *   hasData: this.rows().length > 0,
+ *   reason: 'mode',
+ * });
+ * this.isLoading.set(kind === 'loading');
+ * if (kind === 'loading') {
+ *   this.rows.set([]);
+ * }
+ * ```
+ */
+declare function listFetchKind(options: {
+    hasData: boolean;
+    reason: ListFetchReason;
+}): ListFetchKind;
+
+/**
+ * Shared TanStack Query defaults for AFRICANIES consuming apps.
+ *
+ * `@tanstack/angular-query-experimental` is **not** a dependency of this SDK —
+ * query cache lifetime is app state. These helpers return a plain
+ * `defaultOptions` object you pass into your own `QueryClient`.
+ *
+ * Pin an **exact** `@tanstack/angular-query-experimental` version in the app
+ * (no caret/tilde): TanStack marks the Angular adapter experimental and
+ * breaking changes land without major bumps.
+ *
+ * Query retries default to **0** to match {@link ApiClient} (fail fast;
+ * screens use manual Retry). Apps can override per `QueryClient` if needed.
+ */
+/**
+ * Shape compatible with TanStack `QueryClient` `defaultOptions` without
+ * importing `@tanstack/*` into the SDK.
+ */
+interface AfricaniesQueryClientDefaults {
+    queries: {
+        /** Time before a successful query is considered stale (ms). */
+        staleTime: number;
+        /** Unused-query garbage-collection time (ms). */
+        gcTime: number;
+        /** Max failed-fetch retries for queries (default 0 — fail fast). */
+        retry: number;
+        /** Delay between retries when {@link AfricaniesQueryClientDefaults.queries.retry} > 0. */
+        retryDelay: (attemptIndex: number) => number;
+    };
+    mutations: {
+        /** Mutations are not retried by default — side effects must stay explicit. */
+        retry: number;
+    };
+}
+/**
+ * Factory for TanStack `QueryClient` `defaultOptions`.
+ *
+ * @returns Plain defaults object — no Angular providers, no TanStack imports.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts — pin exact experimental version in package.json
+ * import {
+ *   provideAngularQuery,
+ *   QueryClient,
+ * } from '@tanstack/angular-query-experimental';
+ * import { createAfricaniesQueryClientDefaults } from '@africanies/africanies-core';
+ *
+ * const queryClient = new QueryClient({
+ *   defaultOptions: createAfricaniesQueryClientDefaults(),
+ * });
+ *
+ * export const appConfig = {
+ *   providers: [provideAngularQuery(queryClient)],
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Map injectQuery() signals → AsyncQueryStateModel for <africanies-async-state>
+ * import type { AsyncQueryStateModel } from '@africanies/africanies-models';
+ * import { injectQuery } from '@tanstack/angular-query-experimental';
+ *
+ * const query = injectQuery(() => ({
+ *   queryKey: ['shipments'],
+ *   queryFn: () => firstValueFrom(api.getResource<Shipment>('shipments', null)),
+ * }));
+ *
+ * const state: AsyncQueryStateModel<Shipment[] | null> = {
+ *   data: query.data()?.data ?? undefined,
+ *   isLoading: query.isLoading(),
+ *   isFetching: query.isFetching(),
+ *   isError: query.isError(),
+ *   error: query.error()?.message ?? null,
+ * };
+ * ```
+ */
+declare function createAfricaniesQueryClientDefaults(): AfricaniesQueryClientDefaults;
+/**
+ * Alias of {@link createAfricaniesQueryClientDefaults} for apps that prefer a
+ * `provide*` naming style beside {@link provideAfricaniesSdk}.
+ *
+ * Returns a plain object (not `EnvironmentProviders`) so it can be passed
+ * straight into `new QueryClient({ defaultOptions: ... })`.
+ *
+ * @returns Same object as {@link createAfricaniesQueryClientDefaults}.
+ *
+ * @example
+ * ```ts
+ * const queryClient = new QueryClient({
+ *   defaultOptions: provideAfricaniesQueryDefaults(),
+ * });
+ * ```
+ */
+declare function provideAfricaniesQueryDefaults(): AfricaniesQueryClientDefaults;
+
+/** Public mode-config endpoint path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const MODE_CONFIG_PATH = "/public/mode/config";
+/**
+ * Deep-map mode config preserving snake_case region fields.
+ * @param raw
+ */
+declare function mapModeConfigData(raw: ModeConfigDataModel | Record<string, unknown>): ModeConfigDataModel;
+/**
+ * Resolve currency and measurement units for a country within a shipping mode.
+ * @param config
+ * @param mode
+ * @param countryCode
+ */
+declare function resolveModeRegionConfig(config: ModeConfigDataModel | null | undefined, mode: ShippingMode, countryCode: string | null | undefined): ModeRegionConfigModel;
+
+/**
+ * Source of truth for region currency and measurement units (STN / SFN).
+ *
+ * On startup (via {@link provideModeConfig}), loads
+ * `GET /public/mode/config`, normalizes snake_case wire fields once, and
+ * persists the mapped record to storage. {@link getRegionConfig} reads that
+ * saved record and resolves by country code + active shipping mode.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * providers: [
+ *   provideAfricaniesSdk({ baseUrl: 'https://test-api-export.africaniestest.com/api' }),
+ *   provideHttpClient(withInterceptors([shipmentModeInterceptor])),
+ *   provideModeConfig(),
+ * ];
+ *
+ * // feature — format for shipment origin country
+ * const modeConfig = inject(ModeConfigService);
+ * const region = modeConfig.getRegionConfig('us');
+ * if (region) {
+ *   console.log(region.currency_symbol, region.mass_unit);
+ * }
+ * ```
+ */
+declare class ModeConfigService {
+    private readonly api;
+    private readonly storage;
+    private readonly shippingMode;
+    private readonly _config;
+    private readonly _loading;
+    /** Latest mode-config record (storage hydrate or last successful fetch). */
+    readonly config: Signal<ModeConfigDataModel | null>;
+    /** `true` while {@link loadConfig} is in flight. */
+    readonly loading: Signal<boolean>;
+    constructor();
+    /**
+     * Fetches mode config from the server, updates {@link config}, and persists.
+     *
+     * @returns Normalized API envelope; errors propagate to subscribers.
+     */
+    loadConfig(): Observable<ApiResponseModel<ModeConfigDataModel>>;
+    /**
+     * Region units and currency for a country code under the active (or given) mode.
+     *
+     * @param countryCode - e.g. `'ng'`, `'us'`, `'cn'` — unknown keys use `default`.
+     * @param appType - Defaults to {@link ShippingModeService.mode}.
+     * @returns Resolved region, or `null` before the first load/hydrate.
+     */
+    getRegionConfig(countryCode: string | null | undefined, appType?: ModeAppType): ModeRegionConfigModel | null;
+    /**
+     * Replace the in-memory record and persist — used after {@link loadConfig}.
+     * @param config
+     */
+    private saveRecord;
+    /** Restore the last saved server record so region lookups work offline. */
+    private hydrateFromStorage;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ModeConfigService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ModeConfigService>;
+}
+
+/**
+ * Fetches `/public/mode/config` on app startup and hydrates {@link ModeConfigService}.
+ *
+ * Failures do not block bootstrap — cached storage (if any) remains usable.
+ * Pair with {@link provideAfricaniesSdk} and a real {@link AfricaniesSdkConfig.baseUrl}.
+ *
+ * @returns Environment providers that run the mode-config initializer.
+ */
+declare function provideModeConfig(): EnvironmentProviders;
+
+/** Public country-read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const COUNTRY_READ_PATH = "/public/country/read";
+/**
+ * Map a wire state object into {@link CountryStateModel} (snake_case preserved).
+ * @param raw - State object from the wire.
+ * @returns Normalized {@link CountryStateModel}.
+ */
+declare function mapCountryState(raw: unknown): CountryStateModel;
+/**
+ * Map a wire country object into {@link CountryModel} (snake_case preserved).
+ * @param raw - Country object from the wire.
+ * @returns Normalized {@link CountryModel}.
+ */
+declare function mapCountry(raw: unknown): CountryModel;
+/**
+ * Map a list (or single object) payload into {@link CountryModel}[].
+ *
+ * @param raw - `data` payload from `/public/country/read/{id|all}`.
+ * @returns Mapped country list (empty when `raw` is null/undefined).
+ */
+declare function mapCountryList(raw: unknown): CountryModel[];
+
+/**
+ * Public country utility reads (`GET /public/country/read/{id?}`).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link CountryModel}
+ *
+ * @example
+ * ```ts
+ * const countries = inject(CountryService);
+ *
+ * countries.read(null, { page: 1 }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ *
+ * countries.readAll().subscribe((res) => console.log(res.data?.length));
+ * countries.readById(1).subscribe((res) => console.log(res.data?.name));
+ * ```
+ */
+declare class CountryService {
+    private readonly api;
+    /**
+     * Paginated country page — {@link ResourceId} `null`.
+     *
+     * @param id - Omit or pass `null` for a paginated list.
+     * @param params - Optional page/size/order and filters.
+     */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<CountryModel[]>>;
+    /**
+     * Full country list — {@link ResourceId} `'all'`.
+     *
+     * @param id - Must be `'all'`.
+     * @param params - Optional filters (pagination fields ignored).
+     */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<CountryModel[]>>;
+    /**
+     * Single country — {@link ResourceId} number.
+     *
+     * @param id - Country id.
+     * @param params - Optional filters (pagination fields ignored).
+     */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<CountryModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<CountryModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<CountryModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<CountryModel>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CountryService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CountryService>;
+}
+
+/** Default CDN for ISO country flags ([flagcdn.com](https://flagcdn.com)). */
+declare const COUNTRY_FLAG_CDN_BASE = "https://flagcdn.com";
+/** Image format supported by the flag CDN. */
+type CountryFlagFormat = 'png' | 'webp' | 'jpg' | 'svg';
+/**
+ * Options for {@link countryFlagUrl}.
+ */
+interface CountryFlagUrlOptions {
+    /** Pixel width (`w{width}` on flagcdn). Default `40`. */
+    width?: number;
+    /** Pixel height (`h{height}` on flagcdn). Used instead of {@link width} when set. */
+    height?: number;
+    /** Image format. Default `'png'`. */
+    format?: CountryFlagFormat;
+}
+/**
+ * Select row shape for country pickers (maps cleanly to {@link SelectOption.prefixImageUrl} in UI).
+ */
+interface CountrySelectOption {
+    label: string;
+    value: number;
+    iso2: string;
+    prefixImageUrl: string;
+}
+/**
+ * Build a flagcdn.com URL from an ISO 3166-1 alpha-2 code.
+ *
+ * Examples:
+ * - `countryFlagUrl('NG')` → `https://flagcdn.com/w40/ng.png`
+ * - `countryFlagUrl('us', { width: 80, format: 'webp' })` → `https://flagcdn.com/w80/us.webp`
+ *
+ * @param iso2 - Two-letter country code (case-insensitive).
+ * @param options - Width, height, or format overrides.
+ * @returns CDN URL, or `''` when `iso2` is not two letters.
+ */
+declare function countryFlagUrl(iso2: string, options?: CountryFlagUrlOptions): string;
+/**
+ * Map {@link CountryModel} rows into select options with flag CDN URLs.
+ *
+ * @param countries - Countries from {@link CountryService.readAll} / `readPage`.
+ * @param options - Passed through to {@link countryFlagUrl}.
+ */
+declare function mapCountrySelectOptions(countries: CountryModel[] | null | undefined, options?: CountryFlagUrlOptions): CountrySelectOption[];
+
+/** Public document read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const DOCUMENT_READ_PATH = "/public/document/read";
+/**
+ * Map a wire document into {@link DocumentModel} (snake_case preserved).
+ * @param raw - Single document object from the API.
+ * @returns Normalized {@link DocumentModel}.
+ */
+declare function mapDocument(raw: unknown): DocumentModel;
+/**
+ * Map a list (or single object) payload into {@link DocumentModel}[].
+ * @param raw - `data` payload from `/public/document/read/{id|all}`.
+ * @returns Mapped document list.
+ */
+declare function mapDocumentList(raw: unknown): DocumentModel[];
+
+/**
+ * Public document catalog reads (`GET /public/document/read/{id?}`).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link DocumentModel} (may include preview `url` / `base_64`)
+ *
+ * @example
+ * ```ts
+ * const documents = inject(DocumentService);
+ *
+ * documents.readPage({ page: 1 }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ * documents.readById(12).subscribe((res) => {
+ *   console.log(res.data?.url ?? res.data?.base_64);
+ * });
+ * ```
+ */
+declare class DocumentService {
+    private readonly api;
+    /** Paginated document page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<DocumentModel[]>>;
+    /** Full document list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<DocumentModel[]>>;
+    /** Single document — {@link ResourceId} number. */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<DocumentModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<DocumentModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<DocumentModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<DocumentModel>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DocumentService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DocumentService>;
+}
+
+/** Public plan read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const PLAN_READ_PATH = "/public/plan/read";
+/**
+ * Map a wire plan package into {@link PlanPackageModel}.
+ * @param raw - Package object nested under a plan.
+ * @returns Normalized {@link PlanPackageModel}.
+ */
+declare function mapPlanPackage(raw: unknown): PlanPackageModel;
+/**
+ * Map a wire plan into {@link PlanModel} (snake_case preserved).
+ * @param raw - Single plan object from the API.
+ * @returns Normalized {@link PlanModel}.
+ */
+declare function mapPlan(raw: unknown): PlanModel;
+/**
+ * Map a list (or single object) payload into {@link PlanModel}[].
+ * @param raw - `data` payload from `/public/plan/read/{id|all}`.
+ * @returns Mapped plan list.
+ */
+declare function mapPlanList(raw: unknown): PlanModel[];
+
+/**
+ * Public subscription-plan reads (`GET /public/plan/read/{id?}`).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link PlanModel}
+ *
+ * @example
+ * ```ts
+ * const plans = inject(PlanService);
+ *
+ * plans.readPage({ page: 1, order: 'desc' }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ * plans.readById(1).subscribe((res) => {
+ *   console.log(res.data?.packages?.length);
+ * });
+ * ```
+ */
+declare class PlanService {
+    private readonly api;
+    /** Paginated plan page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<PlanModel[]>>;
+    /** Full plan list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<PlanModel[]>>;
+    /** Single plan — {@link ResourceId} number. */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<PlanModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<PlanModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<PlanModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<PlanModel>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PlanService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PlanService>;
+}
+
+/** Public service read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const SERVICE_READ_PATH = "/public/service/read";
+/**
+ * Map a wire service into {@link ServiceModel} (snake_case preserved).
+ * @param raw - Single service object from the API.
+ * @returns Normalized {@link ServiceModel}.
+ */
+declare function mapService(raw: unknown): ServiceModel;
+/**
+ * Map a list (or single object) payload into {@link ServiceModel}[].
+ * @param raw - `data` payload from `/public/service/read/{id|all}`.
+ * @returns Mapped service list.
+ */
+declare function mapServiceList(raw: unknown): ServiceModel[];
+
+/**
+ * Public subscription-service reads (`GET /public/service/read/{id?}`).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link ServiceModel}
+ *
+ * @example
+ * ```ts
+ * const services = inject(ServiceService);
+ *
+ * services.readPage({ page: 1, search: 'box' }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ * services.readAll().subscribe((res) => console.log(res.data?.length));
+ * services.readById(3).subscribe((res) => console.log(res.data?.name));
+ * ```
+ */
+declare class ServiceService {
+    private readonly api;
+    /** Paginated service page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<ServiceModel[]>>;
+    /** Full service list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<ServiceModel[]>>;
+    /** Single service — {@link ResourceId} number. */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<ServiceModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<ServiceModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<ServiceModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<ServiceModel>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ServiceService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ServiceService>;
+}
+
+/** Currency read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const CURRENCY_READ_PATH = "/currency/read";
+/** Create path (App Settings → Currencies). */
+declare const CURRENCY_CREATE_PATH = "/currency/create";
+/** Update path — name / short_code are not sent. */
+declare const CURRENCY_UPDATE_PATH = "/currency/update";
+/** Delete path — JSON body `{ id }`. */
+declare const CURRENCY_DELETE_PATH = "/currency/delete";
+/**
+ * Serialize a boolean / `"1"` / `"0"` flag for currency create/update.
+ * @param value - Host boolean or wire flag.
+ * @returns `"1"` or `"0"`.
+ */
+declare function toCurrencyFlag01(value: boolean | CurrencyFlag01 | number | null | undefined): CurrencyFlag01;
+/**
+ * Map a currency ↔ payment-method pivot (snake_case preserved).
+ * @param raw - Pivot object from the wire.
+ * @returns Normalized {@link CurrencyPaymentMethodPivotModel}.
+ */
+declare function mapCurrencyPaymentMethodPivot(raw: unknown): CurrencyPaymentMethodPivotModel;
+/**
+ * Map a wire payment method into {@link CurrencyPaymentMethodModel}.
+ * @param raw - Payment-method object from the wire.
+ * @returns Normalized {@link CurrencyPaymentMethodModel}.
+ */
+declare function mapCurrencyPaymentMethod(raw: unknown): CurrencyPaymentMethodModel;
+/**
+ * Map a wire currency into {@link CurrencyModel} (snake_case preserved).
+ * @param raw - Currency object from the API.
+ * @returns Normalized {@link CurrencyModel}.
+ */
+declare function mapCurrency(raw: unknown): CurrencyModel;
+/**
+ * Map a list (or single object) payload into {@link CurrencyModel}[].
+ *
+ * @param raw - `data` payload from `/currency/read/{id|all}`.
+ * @returns Mapped currency list (empty when `raw` is null/undefined).
+ */
+declare function mapCurrencyList(raw: unknown): CurrencyModel[];
+/**
+ * Wire body for `POST /currency/create`.
+ * @param body - Host create payload.
+ * @returns JSON body with `"1"` / `"0"` flags.
+ */
+declare function toCurrencyCreateBody(body: CurrencyCreateRequestModel | null | undefined): {
+    name: string;
+    short_code: string;
+    multiplication_rate: string;
+    division_rate: string;
+    active: CurrencyFlag01;
+    is_naira_greater: CurrencyFlag01;
+    payment_method_ids: number[];
+};
+/**
+ * Wire body for `PUT /currency/update` (no name / short_code).
+ * @param body - Host update payload.
+ * @returns JSON body with `"1"` / `"0"` flags.
+ */
+declare function toCurrencyUpdateBody(body: CurrencyUpdateRequestModel | null | undefined): {
+    id: number;
+    multiplication_rate: string;
+    division_rate: string;
+    active: CurrencyFlag01;
+    is_naira_greater: CurrencyFlag01;
+    payment_method_ids: number[];
+};
+/**
+ * Wire body for `DELETE /currency/delete`.
+ * @param body - Currency id wrapper.
+ * @returns `{ id }`.
+ */
+declare function toCurrencyDeleteBody(body: CurrencyDeleteRequestModel | number | null | undefined): {
+    id: number;
+};
+
+/**
+ * Currency App Settings API (`GET /currency/read/{id?}` plus create / update / delete).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention for reads:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link CurrencyModel}
+ *
+ * Paginated responses embed a Laravel paginator in `data`; {@link ApiClient}
+ * flattens that to `data: CurrencyModel[]` plus `pagination`.
+ *
+ * Writes send `"1"` / `"0"` flags. Delete uses a JSON `{ id }` body (not query
+ * params). After each write, show `res.message` and call {@link readPage} again.
+ *
+ * @example
+ * ```ts
+ * const currencies = inject(CurrencyService);
+ *
+ * currencies.readPage({ page: 1, order: 'desc' }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ * currencies.readAll().subscribe((res) => console.log(res.data?.[0]?.short_code));
+ * currencies.readById(5).subscribe((res) => console.log(res.data?.name));
+ * ```
+ */
+declare class CurrencyService {
+    private readonly api;
+    /** Paginated currency page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<CurrencyModel[]>>;
+    /** Full currency list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<CurrencyModel[]>>;
+    /** Single currency — {@link ResourceId} number. */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<CurrencyModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<CurrencyModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<CurrencyModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<CurrencyModel>>;
+    /**
+     * Create a currency (`POST /currency/create`).
+     *
+     * `name` / `short_code` come from the host’s local currency list, not GET.
+     * Flags may be boolean or `"1"` / `"0"`; they are serialized to `"1"` / `"0"`.
+     *
+     * @param body - Create payload.
+     * @returns Normalized envelope — use {@link ApiResponseModel.message}.
+     */
+    create(body: CurrencyCreateRequestModel): Observable<ApiResponseModel<unknown>>;
+    /**
+     * Update rates, flags, and payment methods (`PUT /currency/update`).
+     *
+     * Name and short code are not sent. Before edit, copy the row into the form
+     * (`true` / `false` may stay booleans — this method serializes flags).
+     *
+     * @param body - Update payload including `id`.
+     * @returns Normalized envelope — use {@link ApiResponseModel.message}.
+     */
+    update(body: CurrencyUpdateRequestModel): Observable<ApiResponseModel<unknown>>;
+    /**
+     * Delete a currency (`DELETE /currency/delete`) with JSON body `{ id }`.
+     *
+     * @param body - Currency id or `{ id }`.
+     * @returns Normalized envelope — use {@link ApiResponseModel.message}.
+     */
+    remove(body: CurrencyDeleteRequestModel | number): Observable<ApiResponseModel<unknown>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CurrencyService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CurrencyService>;
+}
+
+/** Payment-method read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const PAYMENT_METHOD_READ_PATH = "/payment_method/read";
+/** Payment-method update path (`PUT`). */
+declare const PAYMENT_METHOD_UPDATE_PATH = "/payment_method/update";
+/**
+ * Serialize a boolean / `"1"` / `"0"` flag for payment-method update.
+ * @param value - Host boolean or wire flag.
+ * @returns `"1"` or `"0"`.
+ */
+declare function toPaymentMethodFlag01(value: boolean | PaymentMethodFlag01 | number | null | undefined): PaymentMethodFlag01;
+/**
+ * Build the wire body for `PUT /payment_method/update`.
+ *
+ * @param body - Host update payload (`active` may be boolean).
+ * @returns Body with `active` as `"1"` / `"0"`.
+ */
+declare function toPaymentMethodUpdateBody(body: PaymentMethodUpdateRequestModel): {
+    id: number;
+    name: string;
+    model: string;
+    active: PaymentMethodFlag01;
+};
+/**
+ * Map a currency nested on a payment method (rates + pivot, no processors).
+ * @param raw - Currency object from `currencies[]`.
+ * @returns Normalized {@link PaymentMethodCurrencyModel}.
+ */
+declare function mapPaymentMethodCurrency(raw: unknown): PaymentMethodCurrencyModel;
+/**
+ * Map a wire payment method into {@link PaymentMethodModel}.
+ * @param raw - Payment-method object from the API.
+ * @returns Normalized {@link PaymentMethodModel}.
+ */
+declare function mapPaymentMethod(raw: unknown): PaymentMethodModel;
+/**
+ * Map a list (or single object) payload into {@link PaymentMethodModel}[].
+ *
+ * @param raw - `data` payload from `/payment_method/read/{id|all}`.
+ * @returns Mapped payment-method list (empty when `raw` is null/undefined).
+ */
+declare function mapPaymentMethodList(raw: unknown): PaymentMethodModel[];
+
+/**
+ * Payment-method App Settings API (`GET /payment_method/read/{id?}` plus update).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention for reads:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link PaymentMethodModel}
+ *
+ * Paginated responses embed a Laravel paginator in `data`; {@link ApiClient}
+ * flattens that to `data: PaymentMethodModel[]` plus `pagination`.
+ *
+ * The only write is {@link update} (active toggle). There is no create or
+ * delete on this board — processors are linked from Currencies via
+ * `payment_method_ids`. After update, show `res.message` and patch the row’s
+ * local `updated_at` — do not reload the full list.
+ *
+ * @example
+ * ```ts
+ * const methods = inject(PaymentMethodService);
+ *
+ * methods.readPage({ page: 1, order: 'desc' }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ * methods.readAll().subscribe((res) => console.log(res.data?.[0]?.name));
+ * methods.readById(4).subscribe((res) => console.log(res.data?.currencies));
+ *
+ * methods.update({
+ *   id: row.id,
+ *   name: row.name,
+ *   model: row.model,
+ *   active: nextActive,
+ * }).subscribe((res) => {
+ *   // toast res.message; patch row.updated_at locally
+ * });
+ * ```
+ */
+declare class PaymentMethodService {
+    private readonly api;
+    /** Paginated payment-method page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<PaymentMethodModel[]>>;
+    /** Full payment-method list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<PaymentMethodModel[]>>;
+    /** Single payment method — {@link ResourceId} number. */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<PaymentMethodModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<PaymentMethodModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<PaymentMethodModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<PaymentMethodModel>>;
+    /**
+     * Toggle / update a payment method (`PUT /payment_method/update`).
+     *
+     * App Settings only edits `active` (status switch). Resend `name` and
+     * `model` from the current row. `active` may be boolean or `"1"` / `"0"`;
+     * this method serializes to `"1"` / `"0"`.
+     *
+     * On success: show {@link ApiResponseModel.message}, patch that row’s
+     * local `updated_at`, and do **not** call {@link readPage} again.
+     *
+     * @param body - Update payload including `id`.
+     * @returns Normalized envelope — use {@link ApiResponseModel.message}.
+     */
+    update(body: PaymentMethodUpdateRequestModel): Observable<ApiResponseModel<unknown>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PaymentMethodService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PaymentMethodService>;
+}
+
+/** Shipment-method read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const SHIPMENT_METHOD_READ_PATH = "/shipment_method/read";
+/**
+ * Map a nested zone object into {@link ShipmentZoneModel}.
+ * @param raw
+ */
+declare function mapShipmentZone(raw: unknown): ShipmentZoneModel | null;
+/**
+ * Map a method↔zone link into {@link ShipmentMethodZoneLinkModel}.
+ * @param raw
+ */
+declare function mapShipmentMethodZoneLink(raw: unknown): ShipmentMethodZoneLinkModel;
+/**
+ * Map a Laravel-style `zone_values` page into {@link ShipmentMethodZonePageModel}.
+ * @param raw
+ */
+declare function mapShipmentMethodZonePage(raw: unknown): ShipmentMethodZonePageModel;
+/**
+ * Map a wire shipment method into {@link ShipmentMethodModel} (snake_case).
+ * @param raw
+ */
+declare function mapShipmentMethod(raw: unknown): ShipmentMethodModel;
+/**
+ * Map a list (or single object) payload into {@link ShipmentMethodModel}[].
+ * @param raw
+ */
+declare function mapShipmentMethodList(raw: unknown): ShipmentMethodModel[];
+
+/**
+ * Shipment method / carrier utility reads (`GET /shipment_method/read/{id?}`).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link ShipmentMethodModel}
+ *
+ * @example
+ * ```ts
+ * const methods = inject(ShipmentMethodService);
+ *
+ * methods.readPage({ page: 1 }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ * methods.readAll().subscribe((res) => console.log(res.data?.[0]?.name));
+ * methods.readById(12).subscribe((res) => console.log(res.data?.name));
+ * ```
+ */
+declare class ShipmentMethodService {
+    private readonly api;
+    /** Paginated method page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<ShipmentMethodModel[]>>;
+    /** Full method list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<ShipmentMethodModel[]>>;
+    /** Single method — {@link ResourceId} number. */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<ShipmentMethodModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<ShipmentMethodModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<ShipmentMethodModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<ShipmentMethodModel>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ShipmentMethodService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ShipmentMethodService>;
+}
+
+/** Warehouse read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const WAREHOUSE_READ_PATH = "/warehouse/read";
+/**
+ * Map warehouse state into {@link WarehouseStateModel} (snake_case).
+ * @param raw
+ */
+declare function mapWarehouseState(raw: unknown): WarehouseStateModel | null;
+/**
+ * Map nested country (same shape as public country utility).
+ * @param raw
+ */
+declare function mapWarehouseCountry(raw: unknown): CountryModel | null;
+/**
+ * Map a wire warehouse into {@link WarehouseModel} (snake_case preserved).
+ * @param raw
+ */
+declare function mapWarehouse(raw: unknown): WarehouseModel;
+/**
+ * Map a list (or single object) payload into {@link WarehouseModel}[].
+ * @param raw
+ */
+declare function mapWarehouseList(raw: unknown): WarehouseModel[];
+
+/**
+ * Warehouse utility reads (`GET /warehouse/read/{id?}`).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link WarehouseModel}
+ *
+ * @example
+ * ```ts
+ * const warehouses = inject(WarehouseService);
+ *
+ * warehouses.readPage({ page: 1 }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ * warehouses.readAll().subscribe((res) => console.log(res.data?.length));
+ * warehouses.readById(37).subscribe((res) => console.log(res.data?.name));
+ * ```
+ */
+declare class WarehouseService {
+    private readonly api;
+    /** Paginated warehouse page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<WarehouseModel[]>>;
+    /** Full warehouse list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<WarehouseModel[]>>;
+    /** Single warehouse — {@link ResourceId} number. */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<WarehouseModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<WarehouseModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<WarehouseModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<WarehouseModel>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WarehouseService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WarehouseService>;
+}
+
+/** Zone read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const ZONE_READ_PATH = "/zone/read/records";
+/**
+ * Map a wire zone into {@link ZoneModel} (snake_case preserved).
+ * @param raw
+ */
+declare function mapZone(raw: unknown): ZoneModel;
+/**
+ * Map a list (or single object) payload into {@link ZoneModel}[].
+ * @param raw
+ */
+declare function mapZoneList(raw: unknown): ZoneModel[];
+
+/**
+ * Zone utility reads (`GET /zone/read/records/{id?}`).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link ZoneModel}
+ *
+ * @example
+ * ```ts
+ * const zones = inject(ZoneService);
+ *
+ * zones.readPage({ page: 1 }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ * zones.readAll().subscribe((res) => console.log(res.data?.length));
+ * zones.readById(1).subscribe((res) => console.log(res.data?.name));
+ * ```
+ */
+declare class ZoneService {
+    private readonly api;
+    /** Paginated zone page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<ZoneModel[]>>;
+    /** Full zone list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<ZoneModel[]>>;
+    /** Single zone — {@link ResourceId} number. */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<ZoneModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<ZoneModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<ZoneModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<ZoneModel>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ZoneService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ZoneService>;
+}
+
+/** Current-user path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const USER_PATH = "/user";
+/** Change-password path after a default-password first login. */
+declare const USER_CHANGE_PASSWORD_PATH = "/user/change/password";
+/** Invalidate every session for the signed-in user. */
+declare const USER_LOGOUT_FROM_ALL_SESSIONS_PATH = "/user/logout-from-all-sessions";
+/**
+ * Map a state row under country.states.
+ * @param raw - State object from the wire.
+ * @returns {@link UserStateModel}, or `null`.
+ */
+declare function mapUserCountryState(raw: unknown): UserStateModel | null;
+/**
+ * Map nested country on the user profile.
+ * @param raw - Country object from the wire.
+ * @returns {@link UserCountryModel}, or `null`.
+ */
+declare function mapUserCountry(raw: unknown): UserCountryModel | null;
+/**
+ * Normalize `state` when the API returns a string (or an object with `name`).
+ * @param raw - Wire `state` field.
+ * @returns String label, or `null`.
+ */
+declare function mapUserStateLabel(raw: unknown): string | null;
+/**
+ * @param raw - Plan package object.
+ * @returns {@link UserPlanPackageModel}, or `null`.
+ */
+declare function mapUserPlanPackage(raw: unknown): UserPlanPackageModel | null;
+/**
+ * @param raw - Plan object.
+ * @returns {@link UserPlanModel}, or `null`.
+ */
+declare function mapUserPlan(raw: unknown): UserPlanModel | null;
+/**
+ * @param raw - Gateway payload object.
+ * @returns {@link UserGatewayPayloadModel}, or `null`.
+ */
+declare function mapUserGatewayPayload(raw: unknown): UserGatewayPayloadModel | null;
+/**
+ * @param raw - Payment payload object (already parsed).
+ * @returns {@link UserPaymentPayloadModel}, or `null`.
+ */
+declare function mapUserPaymentPayload(raw: unknown): UserPaymentPayloadModel | null;
+/**
+ * @param raw - Subscription object.
+ * @returns {@link UserSubscriptionModel}, or `null`.
+ */
+declare function mapUserSubscription(raw: unknown): UserSubscriptionModel | null;
+/**
+ * @param raw - Business account object.
+ * @returns {@link UserBusinessAccountModel}, or `null`.
+ */
+declare function mapUserBusinessAccount(raw: unknown): UserBusinessAccountModel | null;
+/**
+ * @param raw - Account manager object.
+ * @returns {@link UserAccountManagerModel}, or `null`.
+ */
+declare function mapUserAccountManager(raw: unknown): UserAccountManagerModel | null;
+/**
+ * Map a bare wire user object into {@link UserModel} (snake_case preserved).
+ * @param raw - User object from `GET /user` (unwrapped).
+ * @returns Normalized {@link UserModel}.
+ */
+declare function mapUser(raw: unknown): UserModel;
+
+/**
+ * Current authenticated user (`GET /user`).
+ *
+ * The backend returns a **bare** user object (no `{ success, data }` wrapper).
+ * {@link ApiClient} normalizes that into {@link ApiResponseModel}; this service
+ * maps wire fields once into {@link UserModel} (snake_case preserved).
+ *
+ * Requires an access token via {@link AuthTokenService.set}. Not cached — profile
+ * data is auth-sensitive and can change per session.
+ *
+ * After login, if `user.default_password` is set, send the user to
+ * `/onboarding/reset-password` and call {@link changePassword} (current → new).
+ * That page is **not** the email-link forgot-password flow.
+ *
+ * On logout, call {@link logoutFromAllSessions} while the bearer token is still
+ * set, then {@link AuthTokenService.clear}.
+ *
+ * @example
+ * ```ts
+ * const users = inject(UserService);
+ *
+ * users.me().subscribe((res) => {
+ *   if (res.success) console.log(res.data?.email);
+ * });
+ * ```
+ */
+declare class UserService {
+    private readonly api;
+    /**
+     * Fetch the current user.
+     *
+     * @returns Normalized envelope with mapped {@link UserModel} (or `null` data).
+     */
+    me(): Observable<ApiResponseModel<UserModel>>;
+    /**
+     * Change the signed-in user’s password (`POST /user/change/password`).
+     *
+     * Used on first login when {@link UserModel.default_password} is true —
+     * not the email-only {@link AuthService.forgot} flow.
+     *
+     * @param body - Current password plus new password and confirmation.
+     * @returns Normalized envelope (`data` is typically unused).
+     */
+    changePassword(body: ChangePasswordRequestModel): Observable<ApiResponseModel<unknown>>;
+    /**
+     * Sign out of this device and every other session
+     * (`POST /user/logout-from-all-sessions`).
+     *
+     * Call while the bearer token is still set so the interceptor can attach
+     * `Authorization`. Then {@link AuthTokenService.clear} locally.
+     *
+     * @returns Normalized envelope (`data` is typically unused).
+     */
+    logoutFromAllSessions(): Observable<ApiResponseModel<unknown>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UserService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UserService>;
+}
+
+/** User notifications read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const NOTIFICATION_READ_PATH = "/user/notifications/read";
+/** Mark read endpoint (single `{ id }` or `{}` for all). */
+declare const NOTIFICATION_UPDATE_PATH = "/user/notifications/update";
+/**
+ * Parse the Laravel `data` column (JSON string or object) into
+ * {@link NotificationPayloadModel}.
+ * @param raw
+ */
+declare function mapNotificationPayload(raw: unknown): NotificationPayloadModel;
+/**
+ * Map a wire notification row into {@link NotificationModel}.
+ * @param raw
+ */
+declare function mapNotification(raw: unknown): NotificationModel;
+/**
+ * Map wire list payloads into {@link NotificationModel}[].
+ * @param raw
+ */
+declare function mapNotificationList(raw: unknown): NotificationModel[];
+/**
+ * Derive a header/drawer inbox item from a mapped notification.
+ * @param notification
+ */
+declare function mapNotificationInboxItem(notification: NotificationModel | null | undefined): NotificationInboxItemModel;
+
+/**
+ * Authenticated user notifications (`GET /user/notifications/read/{id?}`).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention for paginated / full-list reads.
+ * Notification primary keys are UUID strings — use {@link readOne} for a single row.
+ *
+ * Requires an access token via {@link AuthTokenService.set}. Not cached — inbox
+ * data is auth-sensitive and changes frequently.
+ *
+ * @example
+ * ```ts
+ * const notifications = inject(NotificationService);
+ *
+ * notifications.readAll().subscribe((res) => {
+ *   console.log(res.data?.length);
+ * });
+ * ```
+ */
+declare class NotificationService {
+    private readonly api;
+    /** Paginated inbox page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<NotificationModel[]>>;
+    /** Full inbox list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<NotificationModel[]>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * Size defaults to {@link NOTIFICATION_PAGE_SIZE} (`30`).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<NotificationModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<NotificationModel[]>>;
+    /**
+     * Single notification by UUID (`GET /user/notifications/read/{uuid}`).
+     * @param id
+     */
+    readOne(id: string): Observable<ApiResponseModel<NotificationModel>>;
+    /**
+     * Mark one or all notifications read (`PUT /user/notifications/update`).
+     *
+     * @param id - When set, marks that notification read; omit to mark all read.
+     */
+    markRead(id?: string): Observable<ApiResponseModel<unknown>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NotificationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NotificationService>;
+}
+
+/**
+ * Rewrite a notification portal URL for the active {@link ShippingMode}.
+ *
+ * Swaps `-export` / `-import` host segments and sets `shipment_app` to
+ * `shipfromnaija` (SFN) or `shiptonaija` (STN).
+ * @param link
+ * @param mode
+ */
+declare function resolveNotificationLinkForMode(link: string | null | undefined, mode: ShippingMode): string;
+
+/** File read path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const FILE_READ_PATH = "/file/read";
+/** Query flag for multi-file waybill reads (`POST /file/read?multiple=yes`). */
+declare const FILE_READ_MULTIPLE_PARAM = "yes";
+/**
+ * Map wire `data` into {@link FileReadModel} (snake_case preserved).
+ *
+ * `POST /file/read` returns a single object in `data` (not a list).
+ * If the wire unexpectedly sends a one-element array, the first entry is used.
+ *
+ * @param raw - Envelope `data` from `POST /file/read`.
+ * @returns Normalized {@link FileReadModel}.
+ */
+declare function mapFileRead(raw: unknown): FileReadModel;
+/**
+ * Map a list (or single object) payload into {@link FileReadModel}[].
+ *
+ * Used for `POST /file/read?multiple=yes` (e-commerce waybills).
+ *
+ * @param raw - Envelope `data` from multi-file reads.
+ * @returns Mapped file list (empty when `raw` is null/undefined).
+ */
+declare function mapFileReadList(raw: unknown): FileReadModel[];
+
+/**
+ * File utility reads (`POST /file/read`).
+ *
+ * Primary preview path when a record stores a `file_ref` string (shipments,
+ * tracking items, waybills, KYC, etc.). Body `{ ref }` → `data` with
+ * `mime_type` and `base_64` for `<img>` / PDF viewers.
+ *
+ * Document catalog previews use {@link DocumentService.readById} instead
+ * (`GET /public/document/read/{id}` → `data.file_ref.base_64`).
+ *
+ * @example
+ * ```ts
+ * const files = inject(FileService);
+ *
+ * files.read(item.file_ref).subscribe((res) => {
+ *   if (res.success) console.log(res.data?.base_64);
+ * });
+ *
+ * files.readMultiple(waybillRef).subscribe((res) => {
+ *   console.log(res.data?.map((f) => f.mime_type));
+ * });
+ * ```
+ */
+declare class FileService {
+    private readonly api;
+    /**
+     * Resolve one file reference (`POST /file/read`, body `{ ref }`).
+     *
+     * @param ref - Storage / document UUID from `file_ref` on a record.
+     * @returns Normalized envelope with mapped {@link FileReadModel}.
+     */
+    read(ref: string): Observable<ApiResponseModel<FileReadModel>>;
+    /**
+     * Resolve multiple files for one ref (`POST /file/read?multiple=yes`).
+     *
+     * E-commerce waybill flows may return several pages in `data[]`.
+     *
+     * @param ref - Storage reference token.
+     * @returns Normalized envelope with mapped {@link FileReadModel}[].
+     */
+    readMultiple(ref: string): Observable<ApiResponseModel<FileReadModel[]>>;
+    /**
+     * Resolve a file from an explicit request body.
+     *
+     * @param body - Wire body (`{ ref }`).
+     * @returns Normalized envelope with mapped {@link FileReadModel}.
+     */
+    readByBody(body: FileReadRequestModel): Observable<ApiResponseModel<FileReadModel>>;
+    /**
+     * Multi-file variant of {@link readByBody}.
+     *
+     * @param body - Wire body (`{ ref }`).
+     * @returns Normalized envelope with mapped {@link FileReadModel}[].
+     */
+    readByBodyMultiple(body: FileReadRequestModel): Observable<ApiResponseModel<FileReadModel[]>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FileService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FileService>;
+}
+
+/** Product read base path (relative to {@link AfricaniesSdkConfig.baseUrl}). */
+declare const PRODUCT_READ_PATH = "/product/read";
+/**
+ * Map a wire product into {@link ProductModel} (snake_case preserved).
+ * @param raw - Single product object from the API.
+ * @returns Normalized {@link ProductModel}.
+ */
+declare function mapProduct(raw: unknown): ProductModel;
+/**
+ * Map a list (or single object) payload into {@link ProductModel}[].
+ * @param raw - `data` payload from `/product/read/{id|all}`.
+ * @returns Mapped product list.
+ */
+declare function mapProductList(raw: unknown): ProductModel[];
+
+/**
+ * Product utility reads (`GET /product/read/{id?}`).
+ *
+ * Uses the AFRICANIES {@link ResourceId} convention:
+ * - `null` (default) → paginated page
+ * - `'all'` → full list
+ * - `number` → single {@link ProductModel}
+ *
+ * @example
+ * ```ts
+ * const products = inject(ProductService);
+ *
+ * products.readPage({ page: 1 }).subscribe((res) => {
+ *   console.log(res.data, res.pagination);
+ * });
+ * products.readAll().subscribe((res) => console.log(res.data?.[0]?.hs_code));
+ * products.readById(6280).subscribe((res) => console.log(res.data?.name));
+ * ```
+ */
+declare class ProductService {
+    private readonly api;
+    /** Paginated product page — {@link ResourceId} `null`. */
+    read(id?: null, params?: ResourceQueryParams): Observable<ApiResponseModel<ProductModel[]>>;
+    /** Full product list — {@link ResourceId} `'all'`. */
+    read(id: 'all', params?: ResourceQueryParams): Observable<ApiResponseModel<ProductModel[]>>;
+    /** Single product — {@link ResourceId} number. */
+    read(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<ProductModel>>;
+    /**
+     * Paginated page — alias for {@link read}(`null`, params).
+     * @param params
+     */
+    readPage(params?: ResourceQueryParams): Observable<ApiResponseModel<ProductModel[]>>;
+    /**
+     * Full list — alias for {@link read}(`'all'`).
+     * @param params
+     */
+    readAll(params?: ResourceQueryParams): Observable<ApiResponseModel<ProductModel[]>>;
+    /**
+     * Single record — alias for {@link read}(id).
+     * @param id
+     * @param params
+     */
+    readById(id: number, params?: ResourceQueryParams): Observable<ApiResponseModel<ProductModel>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ProductService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ProductService>;
+}
+
+/** One select row for filter drawer `optionLists` (wire value + label). */
+interface FilterSelectOption {
+    value: string;
+    label: string;
+    /** Optional leading text/emoji (e.g. country flag emoji) in select rows. */
+    prefixText?: string;
+    /** Optional leading image URL (e.g. {@link countryFlagUrl} flag CDN). */
+    prefixImageUrl?: string;
+}
+/** Host bag keyed by {@link FilterFieldModel.key}. */
+type FilterOptionLists = Record<string, FilterSelectOption[]>;
+/** Select field with a required, non-static {@link FilterOptionsSource}. */
+type ResolvableSelectField = Omit<FilterFieldModel, 'optionsSource' | 'type'> & {
+    type: 'select';
+    optionsSource: Exclude<FilterOptionsSource, 'static'>;
+};
+/**
+ * Select fields that declare a non-static {@link FilterOptionsSource}.
+ *
+ * @param config - Module filter schema.
+ * @returns Fields that need async option resolution.
+ */
+declare function collectResolvableSelectFields(config: ModuleFilterConfigModel | null | undefined): ResolvableSelectField[];
+/**
+ * Unique {@link FilterOptionsSource} values referenced by a config (excluding static).
+ *
+ * @param config - Module filter schema.
+ */
+declare function collectFilterOptionsSources(config: ModuleFilterConfigModel): FilterOptionsSource[];
+/**
+ * Map {@link WarehouseModel}[] into filter select options (`value` = id string).
+ *
+ * @param rows - Warehouses from {@link WarehouseService.readAll}.
+ */
+declare function mapWarehouseFilterOptions(rows: WarehouseModel[] | null | undefined): FilterSelectOption[];
+/**
+ * Map {@link ShipmentMethodModel}[] into filter select options.
+ *
+ * @param rows - Methods from {@link ShipmentMethodService.readAll}.
+ */
+declare function mapShipmentMethodFilterOptions(rows: ShipmentMethodModel[] | null | undefined): FilterSelectOption[];
+/**
+ * Merge SDK-resolved lists with host overrides (host wins per field key).
+ *
+ * @param resolved - Output from {@link FilterOptionsResolver.resolve}.
+ * @param overrides - Host catalogs (e.g. manifests without a built-in service).
+ */
+declare function mergeFilterOptionLists(resolved: FilterOptionLists, overrides?: FilterOptionLists | null): FilterOptionLists;
+
+/**
+ * Resolves filter drawer select options from built-in SDK catalog services.
+ *
+ * Prefer opening {@link FilterDrawerService} immediately — the drawer lazy-loads
+ * per field via {@link resolveField}. {@link resolve} remains for bulk prefetch.
+ *
+ * @example
+ * ```ts
+ * const resolver = inject(FilterOptionsResolver);
+ *
+ * filterDrawer.open({
+ *   config: updateShipmentsFilterConfig,
+ *   optionLists: { shipment_manifest_id: hostManifests },
+ * });
+ * ```
+ */
+declare class FilterOptionsResolver {
+    private readonly warehouses;
+    private readonly shipmentMethods;
+    /**
+     * Resolve SDK-backed options for one select field (lazy drawer load).
+     *
+     * @param field - Filter schema field with `optionsSource`.
+     * @returns Select rows or an error when the catalog HTTP call fails.
+     */
+    resolveField(field: FilterFieldModel): Observable<FilterSelectOption[]>;
+    /**
+     * Resolve all SDK-backed select options for a module config (bulk prefetch).
+     *
+     * @param config - Module filter schema.
+     * @returns `optionLists` keyed by field.key.
+     */
+    resolve(config: ModuleFilterConfigModel): Observable<FilterOptionLists>;
+    private staticFieldOptions;
+    private fetchSource;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FilterOptionsResolver, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FilterOptionsResolver>;
+}
+
+/**
+ * Maps a query-param value to a component and overlay surface.
+ *
+ * Used by {@link RouteOverlayService} when a registered param key's value
+ * matches a key in {@link OverlayRouteConfig.routes}.
+ */
+interface OverlayRouteEntry {
+    /** Standalone component type to open in the overlay. */
+    component: Type<unknown>;
+    /**
+     * Which overlay host to use.
+     * `'modal'` → {@link MODAL_SERVICE}; `'drawer'` → {@link DRAWER_SERVICE}.
+     */
+    overlay: 'modal' | 'drawer';
+}
+/**
+ * One query-param namespace and its value → component map.
+ *
+ * Multiple configs can coexist (e.g. `modal` and `drawer` param keys) so
+ * both surfaces can be driven from the URL at once.
+ *
+ * @example
+ * ```ts
+ * const config: OverlayRouteConfig = {
+ *   paramKey: 'modal',
+ *   routes: {
+ *     'edit-shipment': { component: EditShipmentModal, overlay: 'modal' },
+ *   },
+ * };
+ * ```
+ */
+interface OverlayRouteConfig {
+    /**
+     * Query param name that triggers overlays (e.g. `'modal'` or `'drawer'`).
+     */
+    paramKey: string;
+    /**
+     * Map of param values to overlay entries.
+     * Unknown values are ignored (no open, no error).
+     */
+    routes: Record<string, OverlayRouteEntry>;
+}
+
+/**
+ * Handle returned by modal/drawer openers so route sync can close and
+ * observe dismissal without depending on `@africanies/africanies-ui`.
+ *
+ * @typeParam TResult - Value passed to `close(result)` by the overlay content.
+ */
+interface OverlayHandle<TResult = unknown> {
+    /**
+     * Closes the overlay, optionally with a result.
+     *
+     * @param result - Value forwarded to `afterClosed` subscribers.
+     */
+    close(result?: TResult): void;
+    /**
+     * Emits once when the overlay finishes closing, then completes.
+     */
+    afterClosed(): Observable<TResult | undefined>;
+}
+/**
+ * Minimal opener contract implemented by UI `ModalService` / `DrawerService`.
+ *
+ * Defined in `africanies-core` (and provided from `africanies-ui`) so route-driven
+ * overlays do not create a circular package dependency.
+ */
+interface OverlayOpener {
+    /**
+     * Opens `component` in an overlay host.
+     *
+     * @param component - Standalone component type to instantiate.
+     * @param config - Optional data bag (other query params) and close behavior.
+     */
+    open<TData = unknown, TResult = unknown>(component: Type<unknown>, config?: {
+        data?: TData;
+        dismissible?: boolean;
+    }): OverlayHandle<TResult>;
+}
+/**
+ * Optional token for the app's modal opener (provided by `@africanies/africanies-ui`).
+ *
+ * {@link RouteOverlayService} injects this with `{ optional: true }` so apps
+ * can register route overlays before UI is wired — opens are skipped until
+ * a provider exists.
+ */
+declare const MODAL_SERVICE: InjectionToken<OverlayOpener>;
+/**
+ * Optional token for the app's drawer opener (provided by `@africanies/africanies-ui`).
+ *
+ * Same optional pattern as {@link MODAL_SERVICE}.
+ */
+declare const DRAWER_SERVICE: InjectionToken<OverlayOpener>;
+/**
+ * DI token for the list of {@link OverlayRouteConfig} registered via
+ * {@link provideOverlayRoutes}.
+ */
+declare const OVERLAY_ROUTE_CONFIGS: InjectionToken<OverlayRouteConfig[]>;
+
+/**
+ * Registers query-param → overlay maps and eagerly starts {@link RouteOverlayService}.
+ *
+ * Call beside {@link provideAfricaniesSdk} in `app.config.ts`. Modal/drawer openers
+ * must still be provided by `@africanies/africanies-ui` (`MODAL_SERVICE` / `DRAWER_SERVICE`).
+ *
+ * @param configs - One or more param-key namespaces (e.g. `modal` and `drawer`).
+ * @returns Environment providers including an app initializer.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * import { provideRouter, Routes } from '@angular/router';
+ * import {
+ *   provideAfricaniesSdk,
+ *   provideOverlayRoutes,
+ * } from '@africanies/africanies-core';
+ * import { EditShipmentModal } from './edit-shipment.modal';
+ *
+ * export const appConfig = {
+ *   providers: [
+ *     provideAfricaniesSdk({ baseUrl: 'https://api.example.com' }),
+ *     provideRouter(routes),
+ *     provideOverlayRoutes([
+ *       {
+ *         paramKey: 'modal',
+ *         routes: {
+ *           'edit-shipment': {
+ *             component: EditShipmentModal,
+ *             overlay: 'modal',
+ *           },
+ *         },
+ *       },
+ *     ]),
+ *     // From @africanies/africanies-ui — binds MODAL_SERVICE / DRAWER_SERVICE
+ *     // provideAfricaniesOverlays(),
+ *   ],
+ * };
+ *
+ * // Template — open via query params (refresh with the same URL reopens):
+ * // <a routerLink="." [queryParams]="{ modal: 'edit-shipment', id: row.id }">
+ * //   Edit
+ * // </a>
+ * ```
+ */
+declare function provideOverlayRoutes(configs: OverlayRouteConfig[]): EnvironmentProviders;
+
+/**
+ * Keeps query-param state in sync with modal/drawer overlays.
+ *
+ * Instantiated eagerly via {@link provideOverlayRoutes}'s `provideAppInitializer`
+ * so a hard refresh with `?modal=…` already present reopens the overlay.
+ *
+ * Bidirectional sync:
+ * - Param appears / matches a route → open (passing sibling query params as data)
+ * - Param removed (e.g. browser back) → close without navigating again
+ * - Overlay closed by UI → strip the trigger param with `queryParamsHandling: 'merge'`
+ *
+ * Modal/drawer implementations live in `@africanies/africanies-ui` and are injected through
+ * {@link MODAL_SERVICE} / {@link DRAWER_SERVICE} to avoid a circular dependency.
+ */
+declare class RouteOverlayService {
+    private readonly route;
+    private readonly router;
+    private readonly configs;
+    private readonly modal;
+    private readonly drawer;
+    private readonly openByKey;
+    constructor();
+    private onQueryParams;
+    private syncConfig;
+    private siblingParams;
+    private teardown;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RouteOverlayService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RouteOverlayService>;
+}
+
+/**
+ * Copy plain text to the system clipboard.
+ *
+ * Prefers `navigator.clipboard.writeText`. Falls back to a temporary
+ * `textarea` + `document.execCommand('copy')` when the Clipboard API is
+ * missing or throws (older browsers, some embedded / non-secure contexts).
+ *
+ * Safe to call during SSR — returns `false` when `document` is unavailable.
+ *
+ * @param value - Text to place on the clipboard.
+ * @returns `true` when the write succeeded; `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * const ok = await copyToClipboard(iconName);
+ * if (ok) {
+ *   toast.success(`Copied “${iconName}”`);
+ * }
+ * ```
+ */
+declare function copyToClipboard(value: string): Promise<boolean>;
+
+/** Value that can be serialized into a CSV cell. */
+type CsvCellValue = string | number | boolean | null | undefined;
+/**
+ * Options for {@link downloadCsv}.
+ */
+interface DownloadCsvOptions {
+    /** Download filename, including `.csv`. */
+    filename: string;
+    /** Optional header row. */
+    headers?: readonly CsvCellValue[];
+    /** Data rows. Each inner array is one CSV record. */
+    rows: readonly (readonly CsvCellValue[])[];
+    /**
+     * Prefix a UTF-8 BOM so Excel opens the file as UTF-8. Defaults to `true`.
+     */
+    bom?: boolean;
+}
+/**
+ * Escape a single CSV field (RFC 4180).
+ *
+ * Quotes fields that contain commas, quotes, or line breaks. `null` /
+ * `undefined` become an empty cell.
+ *
+ * @param value - Cell value.
+ */
+declare function csvCell(value: CsvCellValue): string;
+/**
+ * Build a CSV document string (optional BOM + header + rows).
+ *
+ * @param options - Headers, rows, and BOM flag (filename is ignored).
+ */
+declare function toCsvString(options: Pick<DownloadCsvOptions, 'headers' | 'rows' | 'bom'>): string;
+/**
+ * Download a CSV file in the browser.
+ *
+ * Hosts supply filename, headers, and already-mapped row values. Safe during
+ * SSR — returns `false` when `document` is unavailable.
+ *
+ * @param options - Filename, headers, and row cells.
+ * @returns `true` when the download was triggered.
+ *
+ * @example
+ * ```ts
+ * downloadCsv({
+ *   filename: 'warehouses.csv',
+ *   headers: ['Name', 'Status'],
+ *   rows: warehouses.map((row) => [
+ *     row.name,
+ *     row.active ? 'Active' : 'In-Active',
+ *   ]),
+ * });
+ * ```
+ */
+declare function downloadCsv(options: DownloadCsvOptions): boolean;
+
+export { AFRICANIES_HTTP_TOAST, AFRICANIES_SDK_CONFIG, AUTH_FORGOT_PASSWORD_PATH, ApiClient, AuthService, AuthTokenService, COUNTRY_FLAG_CDN_BASE, COUNTRY_READ_PATH, CURRENCY_CREATE_PATH, CURRENCY_DELETE_PATH, CURRENCY_READ_PATH, CURRENCY_UPDATE_PATH, CountryService, CurrencyService, DOCUMENT_READ_PATH, DRAWER_SERVICE, DocumentService, FILE_READ_MULTIPLE_PARAM, FILE_READ_PATH, FileService, FilterOptionsResolver, HttpResponseCache, MODAL_SERVICE, MODE_CONFIG_PATH, ModeConfigService, NOTIFICATION_READ_PATH, NOTIFICATION_UPDATE_PATH, NotificationService, OVERLAY_ROUTE_CONFIGS, PAYMENT_METHOD_READ_PATH, PAYMENT_METHOD_UPDATE_PATH, PLAN_READ_PATH, PRODUCT_READ_PATH, PaymentMethodService, PlanService, ProductService, RouteOverlayService, SERVICE_READ_PATH, SHIPMENT_METHOD_READ_PATH, SHIPPING_MODE_OVERRIDE, ServiceService, ShipmentMethodService, ShippingModeService, TOAST_HTTP_OPTIONS, USER_CHANGE_PASSWORD_PATH, USER_LOGOUT_FROM_ALL_SESSIONS_PATH, USER_PATH, UserService, WAREHOUSE_READ_PATH, WarehouseService, ZONE_READ_PATH, ZoneService, asArray, asBoolean, asNullableBoolean, asNullableFlag01, asNullableNumber, asNullableString, asNumber, asRecord, asShippingMode, asString, authInterceptor, buildResourcePath, buildResourceQueryParams, collectFilterOptionsSources, collectResolvableSelectFields, copyToClipboard, countryFlagUrl, createAfricaniesQueryClientDefaults, csvCell, downloadCsv, fieldErrorsMap, formatApiErrorMessage, httpToastInterceptor, isLaravelValidationBag, isValidEmail, joinApiErrorMessages, listFetchKind, mapApiJsonList, mapApiJsonValue, mapArray, mapCountry, mapCountryList, mapCountrySelectOptions, mapCountryState, mapCurrency, mapCurrencyList, mapCurrencyPaymentMethod, mapCurrencyPaymentMethodPivot, mapDocument, mapDocumentList, mapFileRead, mapFileReadList, mapLaravelValidationBag, mapList, mapModeConfigData, mapNotification, mapNotificationInboxItem, mapNotificationList, mapNotificationPayload, mapPaymentMethod, mapPaymentMethodCurrency, mapPaymentMethodList, mapPlan, mapPlanList, mapPlanPackage, mapProduct, mapProductList, mapResourcePayload, mapService, mapServiceList, mapShipmentMethod, mapShipmentMethodFilterOptions, mapShipmentMethodList, mapShipmentMethodZoneLink, mapShipmentMethodZonePage, mapShipmentZone, mapUser, mapUserAccountManager, mapUserBusinessAccount, mapUserCountry, mapUserCountryState, mapUserGatewayPayload, mapUserPaymentPayload, mapUserPlan, mapUserPlanPackage, mapUserStateLabel, mapUserSubscription, mapWarehouse, mapWarehouseCountry, mapWarehouseFilterOptions, mapWarehouseList, mapWarehouseState, mapZone, mapZoneList, mergeFilterOptionLists, normalize, normalizePagination, provideAfricaniesHttpClient, provideAfricaniesQueryDefaults, provideAfricaniesSdk, provideModeConfig, provideOverlayRoutes, resolveModeRegionConfig, resolveNotificationLinkForMode, resourceCacheTtlMs, shipmentModeInterceptor, toCsvString, toCurrencyCreateBody, toCurrencyDeleteBody, toCurrencyFlag01, toCurrencyUpdateBody, toFlag01, toPaymentMethodFlag01, toPaymentMethodUpdateBody, unwrapLaravelPaginator, withShippingMode, withToast };
+export type { AfricaniesHttpClientOptions, AfricaniesHttpToastHandler, AfricaniesQueryClientDefaults, AfricaniesSdkConfig, AfricaniesSdkHttpToasts, ApiRequestOptions, CountryFlagFormat, CountryFlagUrlOptions, CountrySelectOption, CsvCellValue, DownloadCsvOptions, FilterOptionLists, FilterSelectOption, ListFetchKind, ListFetchReason, OverlayHandle, OverlayOpener, OverlayRouteConfig, OverlayRouteEntry, ResourceQueryParams, ShippingModeChangeGuard, ToastHttpOptions };