@explorins/pers-sdk-react-native 2.3.7 → 2.3.8

package/dist/index.js

@@ -2607,8 +2607,15 @@ exports.TransactionTriggerProcessType = void 0;
     TransactionTriggerProcessType["CAMPAIGN_BUSINESS_CLAIM"] = "CAMPAIGN_BUSINESS_CLAIM";
     TransactionTriggerProcessType["REDEMPTION_SPEND"] = "REDEMPTION_SPEND";
     TransactionTriggerProcessType["REDEMPTION_RECEIVE"] = "REDEMPTION_RECEIVE";
+    /**
+     * Price token transfer during redemption (ERC20/ERC721/ERC1155 payment).
+     * Does NOT trigger reward minting — the redemption lifecycle is driven by
+     * REDEMPTION_SPEND (credit) or direct minting for free redemptions.
+     */
+    TransactionTriggerProcessType["REDEMPTION_PRICE_TOKEN_TRANSFER"] = "REDEMPTION_PRICE_TOKEN_TRANSFER";
     TransactionTriggerProcessType["MIGRATION"] = "MIGRATION";
     TransactionTriggerProcessType["ADMIN_TRIGGERED"] = "ADMIN_TRIGGERED";
+    TransactionTriggerProcessType["BUSINESS_TRIGGERED"] = "BUSINESS_TRIGGERED";
 })(exports.TransactionTriggerProcessType || (exports.TransactionTriggerProcessType = {}));
 
 exports.ApiKeyType = void 0;
@@ -2620,6 +2627,7 @@ exports.ApiKeyType = void 0;
     ApiKeyType["USER_JWT_REFRESH_TOKEN"] = "USER_JWT_REFRESH_TOKEN";
     ApiKeyType["BUSINESS_JWT_ACCESS_TOKEN"] = "BUSINESS_JWT_ACCESS_TOKEN";
     ApiKeyType["BUSINESS_JWT_REFRESH_TOKEN"] = "BUSINESS_JWT_REFRESH_TOKEN";
+    ApiKeyType["BUSINESS_SYSTEM_JWT"] = "BUSINESS_SYSTEM_JWT";
     ApiKeyType["BLOCKCHAIN_WRITER_JWT"] = "BLOCKCHAIN_WRITER_JWT";
     ApiKeyType["BLOCKCHAIN_READER_JWT"] = "BLOCKCHAIN_READER_JWT";
     ApiKeyType["TRANSACTION_JWT_ACCESS_TOKEN"] = "TRANSACTION_JWT_ACCESS_TOKEN";
@@ -2701,6 +2709,11 @@ exports.Web3ContractTypes = void 0;
     Web3ContractTypes["COUNTERFACTUAL_WALLET_PROXY"] = "COUNTERFACTUAL_WALLET_PROXY";
     // Token Contracts
     Web3ContractTypes["TOKEN_CONTRACT"] = "TOKEN_CONTRACT";
+    // Token Deployment Infrastructure
+    Web3ContractTypes["TOKEN_IMPLEMENTATION"] = "TOKEN_IMPLEMENTATION";
+    Web3ContractTypes["TOKEN_PROXY_FACTORY"] = "TOKEN_PROXY_FACTORY";
+    // Notification Infrastructure
+    Web3ContractTypes["NOTIFICATION_HUB"] = "NOTIFICATION_HUB";
 })(exports.Web3ContractTypes || (exports.Web3ContractTypes = {}));
 
 /**
@@ -2737,6 +2750,8 @@ exports.Web3MasterWalletTypes = void 0;
     Web3MasterWalletTypes["PROXY_FACTORY_OWNER"] = "PROXY_FACTORY_OWNER";
     Web3MasterWalletTypes["RELAYER"] = "RELAYER";
     Web3MasterWalletTypes["TOKEN_OWNER"] = "TOKEN_OWNER";
+    Web3MasterWalletTypes["TENANT_WALLET"] = "TENANT_WALLET";
+    Web3MasterWalletTypes["NOTIFIER"] = "NOTIFIER";
 })(exports.Web3MasterWalletTypes || (exports.Web3MasterWalletTypes = {}));
 
 /**
@@ -2751,6 +2766,7 @@ exports.SigningAccountProvider = void 0;
     WALLETCONNECT     = 'walletconnect',
     COINBASE_WALLET   = 'coinbase_wallet', */
     SigningAccountProvider["DFNS"] = "DFNS";
+    SigningAccountProvider["TURNKEY"] = "TURNKEY";
     // CUSTODIAL         = 'custodial'
     SigningAccountProvider["PERS_INTERNAL"] = "PERS_INTERNAL"; // Internal PERS managed signing accounts
 })(exports.SigningAccountProvider || (exports.SigningAccountProvider = {}));
@@ -3156,6 +3172,7 @@ exports.WebhookAuthType = void 0;
     WebhookAuthType["NONE"] = "NONE";
     WebhookAuthType["BEARER"] = "BEARER";
     WebhookAuthType["JWT"] = "JWT";
+    WebhookAuthType["HMAC"] = "HMAC";
 })(exports.WebhookAuthType || (exports.WebhookAuthType = {}));
 /**
  * Sources that can invoke a webhook
@@ -3213,6 +3230,47 @@ const OttAuthMethod = {
     EMAIL_CODE: 'email-code',
 };
 
+/**
+ * Describes the economic mechanism used to issue a reward token.
+ * Persisted on the transaction record for audit, analytics, and AML reporting.
+ *
+ * IMPORTANT: This records economic intent/attribution, not the on-chain executor.
+ * Per-business on-chain execution is a Phase 2 milestone:
+ *   - BUSINESS_BALANCE_TRANSFER: requires transferFrom + allowance or AA smart-wallet as msg.sender
+ *   - BUSINESS_OWNED_MINT: requires per-business MINTER_ROLE (granted eagerly at metadata ownership assignment)
+ * In the interim, business custodial smart wallets are routed through EIP-712 when CUSTODIAL wallet
+ * type is detected (Step 7 of server-transaction.workflow.ts).
+ *
+ * Decision matrix (resolved at claim time by the reward orchestrators):
+ *  ERC20, canMintToken=true               → TENANT_DELEGATED_MINT (tenant master wallet mints)
+ *  ERC20, canMintToken=false              → BUSINESS_BALANCE_TRANSFER (business smart wallet transfers)
+ *  NFT, metadata.ownerBusinessId matches  → BUSINESS_OWNED_MINT (MINTER_ROLE granted at ownership assignment)
+ *  NFT, no business ownership match       → TENANT_DELEGATED_MINT
+ *  Non-reward transactions (transfer, burn, legacy) → null (not set)
+ */
+exports.TokenIssuanceMode = void 0;
+(function (TokenIssuanceMode) {
+    /**
+     * Tenant master wallet mints new supply (default path).
+     * Applies to all NFTs without business-ownership attribution and ERC20 with canMintToken=true.
+     * On-chain: tenant master wallet calls mint(); cost absorbed by platform.
+     */
+    TokenIssuanceMode["TENANT_DELEGATED_MINT"] = "TENANT_DELEGATED_MINT";
+    /**
+     * Business owns the NFT template (metadata.ownerBusinessId matches engaging business).
+     * MINTER_ROLE is eagerly granted to the business custodial wallet at metadata ownership assignment.
+     * On-chain: business custodial smart wallet is msg.sender via EIP-712 path (Step 7).
+     */
+    TokenIssuanceMode["BUSINESS_OWNED_MINT"] = "BUSINESS_OWNED_MINT";
+    /**
+     * Business transfers from its own on-chain ERC20 balance. No new supply created.
+     * Cap = business wallet balance. Triggered when canMintToken=false on the engaging business.
+     * On-chain: business custodial smart wallet is msg.sender via EIP-712 path (Step 7).
+     * Balance pre-check is enforced by validateTokenTransfer (Step 5) before submission.
+     */
+    TokenIssuanceMode["BUSINESS_BALANCE_TRANSFER"] = "BUSINESS_BALANCE_TRANSFER";
+})(exports.TokenIssuanceMode || (exports.TokenIssuanceMode = {}));
+
 /**
  * Base array of all string-valued user model property keys.
  * Single source of truth for user field names across the codebase.
@@ -3529,7 +3587,7 @@ const validateFieldValue = (value, rules, fieldType) => {
             break;
         case 'phone':
             // Basic phone validation - allows digits, spaces, dashes, parentheses, plus
-            const phoneRegex = /^[\d\s\-\(\)\+]+$/;
+            const phoneRegex = /^[\d\s\-()+]+$/;
             if (!phoneRegex.test(stringValue)) {
                 return { field: '', message: 'Invalid phone number format', code: 'phone' };
             }
@@ -3661,6 +3719,399 @@ const validateAllFields = (data, definitions) => {
     return errors;
 };
 
+/**
+ * User status hierarchy resolution (pure, framework-agnostic).
+ *
+ * Centralizes the rule for "does a user's earned status satisfy a minimum
+ * requirement?" so backend and frontend evaluate it identically.
+ *
+ * Hierarchy semantics:
+ * - Exact match always qualifies.
+ * - Otherwise a user qualifies if they hold a status in the SAME hierarchy with
+ *   an `order` greater than or equal to the required status `order`.
+ * - Hierarchies (tracks) are separated by tags: statuses with no tags share the
+ *   global hierarchy; tagged statuses share a track only when their tags overlap.
+ * - A required status without an `order` requires an exact match (backward compatible).
+ */
+/**
+ * Returns true if any two tag arrays share at least one tag (case-insensitive).
+ * Statuses that overlap on tags belong to the same track.
+ */
+function tagsOverlap(tags1, tags2) {
+    if (!tags1.length || !tags2.length)
+        return false;
+    const set1 = new Set(tags1.map(t => t.toLowerCase()));
+    return tags2.some(tag => set1.has(tag.toLowerCase()));
+}
+/**
+ * Determines whether a user meets a minimum status requirement, honoring the
+ * tag-scoped status hierarchy.
+ *
+ * @param requiredStatusId - The minimum status type ID required.
+ * @param userStatusIds - Status type IDs the user has earned.
+ * @param allStatusTypes - All status types (must include the required and user statuses).
+ * @returns True if the user satisfies the requirement (exact match or higher in same track).
+ */
+function meetsMinimumStatusRequirement(requiredStatusId, userStatusIds, allStatusTypes) {
+    // Quick check: exact match
+    if (userStatusIds.includes(requiredStatusId)) {
+        return true;
+    }
+    const statusMap = new Map(allStatusTypes.map(s => [s.id, s]));
+    const requiredStatus = statusMap.get(requiredStatusId);
+    if (!requiredStatus) {
+        return false; // Required status doesn't exist
+    }
+    const requiredOrder = requiredStatus.order;
+    if (requiredOrder === null || requiredOrder === undefined) {
+        // No order on required status = require exact match only (backward compatible)
+        return false;
+    }
+    const requiredTags = requiredStatus.tags || [];
+    // Check if user has any status with equal or higher order in the same hierarchy
+    for (const userStatusId of userStatusIds) {
+        const userStatus = statusMap.get(userStatusId);
+        if (!userStatus)
+            continue;
+        const userOrder = userStatus.order;
+        if (userOrder === null || userOrder === undefined)
+            continue; // No order
+        const userTags = userStatus.tags || [];
+        // Same hierarchy when: both untagged (global), OR they share a track tag.
+        const sameHierarchy = (requiredTags.length === 0 && userTags.length === 0) ||
+            tagsOverlap(requiredTags, userTags);
+        if (!sameHierarchy)
+            continue; // Different hierarchy
+        if (userOrder >= requiredOrder) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Canonical list of redemption eligibility gates.
+ *
+ * ⚠️  SYNC CONTRACT: These gates must mirror the validation steps in
+ * `RedemptionRedeemWorkflow` (backend). If you add or remove a gate here,
+ * update the workflow too — and vice versa.
+ *
+ * Use this constant in tests to assert that `evaluateRedemptionEligibility`
+ * returns exactly these keys (no more, no less):
+ *
+ *   expect(Object.keys(result.checks)).toEqual([...REDEMPTION_ELIGIBILITY_GATES]);
+ */
+const REDEMPTION_ELIGIBILITY_GATES = [
+    'userActive',
+    'requiredFields',
+    'booking',
+    'userStatus',
+    'maxPerUser',
+];
+function makeCheck(passed, code, message, detail) {
+    return passed
+        ? { passed: true, reason: null }
+        : { passed: false, reason: { code, message }, ...(detail ? { detail } : {}) };
+}
+/**
+ * Derives an aggregate redemption eligibility verdict from the user, redemption and status list.
+ *
+ * Pure and side-effect free: pass the DTOs directly from your API responses; the function
+ * computes all per-gate verdicts (including status hierarchy and maxPerUser math) internally.
+ *
+ * Requires `?include=requiredUserInfo,booking` on the redemption fetch and
+ * `?include=status` on the user fetch for full accuracy.
+ */
+function evaluateRedemptionEligibility(input) {
+    const { user, redemption, allStatusTypes, userRedeemCount } = input;
+    const userStatusTypeIds = (user.included?.statusTypes ?? []).map(s => s.id).filter((id) => id !== undefined);
+    const minUserStatusTypeId = redemption.minUserStatusType?.id ?? null;
+    const requiredUserInfo = redemption.included?.requiredUserInfo;
+    const booking = redemption.included?.booking;
+    // userStatus — delegate to shared pure hierarchy check
+    const userStatusPassed = !minUserStatusTypeId ||
+        meetsMinimumStatusRequirement(minUserStatusTypeId, userStatusTypeIds, allStatusTypes);
+    // maxPerUser — pure numeric comparison
+    const maxPerUserPassed = !redemption.maxPerUser || userRedeemCount < redemption.maxPerUser;
+    // requiredFields — use isValid from the include; derive missing keys from field definitions
+    const requiredFieldsPassed = !requiredUserInfo || requiredUserInfo.isValid;
+    const missingFieldKeys = requiredUserInfo?.fieldDefinitions
+        ?.filter(f => f.isMissing)
+        .map(f => f.key ?? f.id ?? '')
+        .filter(Boolean) ?? [];
+    const checks = {
+        userActive: makeCheck(user.isActive !== false, 'USER_INACTIVE', 'User account is inactive'),
+        requiredFields: makeCheck(requiredFieldsPassed, 'MISSING_REQUIRED_FIELDS', 'User is missing one or more required fields', requiredFieldsPassed ? undefined : { missingFieldKeys }),
+        booking: makeCheck(!booking || booking.isValid, 'BOOKING_REQUIRED', 'User does not have a valid booking meeting the requirements'),
+        userStatus: makeCheck(userStatusPassed, 'INSUFFICIENT_USER_STATUS', 'User does not meet the minimum status requirement', userStatusPassed || !minUserStatusTypeId ? undefined : {
+            minRequiredStatusTypeId: minUserStatusTypeId,
+            userStatusTypeIds,
+        }),
+        maxPerUser: makeCheck(maxPerUserPassed, 'MAX_PER_USER_REACHED', 'User has reached the maximum number of redeems allowed', maxPerUserPassed || !redemption.maxPerUser ? undefined : {
+            maxPerUser: redemption.maxPerUser,
+            userRedeemCount,
+        }),
+    };
+    return {
+        isEligible: Object.values(checks).every(c => c.passed),
+        checks,
+    };
+}
+
+/**
+ * Campaign trigger-source access rule (pure, framework-agnostic).
+ *
+ * Single source of truth for "may this business assign/remove/create a trigger
+ * source against this campaign?", shared by CampaignService (assign/remove) and
+ * TriggerSourceService (optional campaignId at creation) — two different NestJS
+ * modules that each fetch the campaign via their own query, but must agree on
+ * the same rule instead of maintaining separate copies.
+ *
+ * Rules:
+ * - No requestingBusinessId (tenant admin) — always allowed.
+ * - Tenant-level campaign (no ownerBusinessId) — allowed for any business; the
+ *   specific trigger source's own businessId ownership is checked separately.
+ * - Business-owned campaign — only the owning business is allowed.
+ */
+function canManageCampaignTriggerSources(campaign, requestingBusinessId) {
+    if (!requestingBusinessId)
+        return true;
+    return !campaign.ownerBusinessId || campaign.ownerBusinessId === requestingBusinessId;
+}
+
+/**
+ * Computed lifecycle status of a campaign/redemption (never stored).
+ * Precedence mirrors assertAvailable: inactive, then ended, then scheduled, else active.
+ */
+exports.AvailabilityStatus = void 0;
+(function (AvailabilityStatus) {
+    AvailabilityStatus["INACTIVE"] = "inactive";
+    AvailabilityStatus["SCHEDULED"] = "scheduled";
+    AvailabilityStatus["ACTIVE"] = "active";
+    AvailabilityStatus["ENDED"] = "ended";
+})(exports.AvailabilityStatus || (exports.AvailabilityStatus = {}));
+
+/** Precedence: inactive, ended, scheduled, active (same order as the SQL status filter). */
+function getAvailabilityStatus(entity, now = new Date()) {
+    if (!entity.isActive)
+        return exports.AvailabilityStatus.INACTIVE;
+    if (entity.endDate && new Date(entity.endDate) < now)
+        return exports.AvailabilityStatus.ENDED;
+    if (entity.startDate && new Date(entity.startDate) > now)
+        return exports.AvailabilityStatus.SCHEDULED;
+    return exports.AvailabilityStatus.ACTIVE;
+}
+function assertAvailable(entity, errors, now = new Date()) {
+    switch (getAvailabilityStatus(entity, now)) {
+        case exports.AvailabilityStatus.INACTIVE: throw errors.notActive();
+        case exports.AvailabilityStatus.ENDED: throw errors.ended(new Date(entity.endDate));
+        case exports.AvailabilityStatus.SCHEDULED: throw errors.notStarted(new Date(entity.startDate));
+    }
+}
+
+/** Opt-in request header; `Accept-Language` is deliberately not used (browsers send it implicitly). */
+const LOCALE_HEADER = 'x-locale';
+const LOCALE_MAX_LENGTH = 35;
+const TRANSLATIONS_MAX_LOCALES = 30;
+const TRANSLATION_VALUE_MAX_LENGTH = 4000;
+const TRANSLATION_FIELD_MAX_LENGTH = 100;
+const TRANSLATIONS_MAX_SIZE = 32 * 1024;
+const LOCALE_PATTERN = /^[a-z]{2,3}(-[a-z0-9]{2,8}){0,3}$/;
+const hasOwn = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+/** Returns a lowercase BCP 47 tag (`en_US` -> `en-us`), or null when absent or malformed. */
+function normalizeLocale(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const value = raw.trim().replace(/_/g, '-').toLowerCase();
+    if (value.length === 0 || value.length > LOCALE_MAX_LENGTH || !LOCALE_PATTERN.test(value))
+        return null;
+    return value;
+}
+/**
+ * Per-field lookup: exact tag, then progressively shorter tags (`ar-sa` -> `ar`), then `base`.
+ * Empty or missing translated values fall through.
+ */
+function resolveTranslation(translations, locale, field, base) {
+    if (!translations || !locale)
+        return base;
+    const parts = locale.split('-');
+    for (let length = parts.length; length > 0; length--) {
+        const key = parts.slice(0, length).join('-');
+        if (!hasOwn(translations, key))
+            continue;
+        const entry = translations[key];
+        if (!entry || !hasOwn(entry, field))
+            continue;
+        const value = entry[field];
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    return base;
+}
+/** Size/count limits for a whole stored map. Returns an error message, or null when valid. */
+function validateTranslationsLimits(map) {
+    if (!map)
+        return null;
+    if (Object.keys(map).length > TRANSLATIONS_MAX_LOCALES) {
+        return `at most ${TRANSLATIONS_MAX_LOCALES} locales are allowed`;
+    }
+    if (JSON.stringify(map).length > TRANSLATIONS_MAX_SIZE) {
+        return `translations exceed the ${TRANSLATIONS_MAX_SIZE} character limit`;
+    }
+    return null;
+}
+/** An allowed entry ending in `*` is a prefix wildcard (e.g. `option.*` for keyed nested texts). */
+function isAllowedField(field, allowedFields) {
+    if (field.length > TRANSLATION_FIELD_MAX_LENGTH)
+        return false;
+    return allowedFields.some(allowed => allowed === field || (allowed.endsWith('*') && field.length >= allowed.length && field.startsWith(allowed.slice(0, -1))));
+}
+/** Structural validation of a write payload. Returns an error message, or null when valid. */
+function validateTranslationsPatch(input, allowedFields) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return 'translations must be an object keyed by locale';
+    }
+    const entries = Object.entries(input);
+    if (entries.length > TRANSLATIONS_MAX_LOCALES) {
+        return `at most ${TRANSLATIONS_MAX_LOCALES} locales are allowed`;
+    }
+    for (const [rawLocale, entry] of entries) {
+        if (normalizeLocale(rawLocale) === null)
+            return `invalid locale "${rawLocale.slice(0, LOCALE_MAX_LENGTH)}"`;
+        if (entry === null)
+            continue;
+        if (typeof entry !== 'object' || Array.isArray(entry)) {
+            return `translations for "${rawLocale}" must be an object or null`;
+        }
+        for (const [field, value] of Object.entries(entry)) {
+            if (!isAllowedField(field, allowedFields))
+                return `field "${field.slice(0, 50)}" is not translatable`;
+            if (value === null)
+                continue;
+            if (typeof value !== 'string')
+                return `"${rawLocale}.${field}" must be a string or null`;
+            if (value.length > TRANSLATION_VALUE_MAX_LENGTH) {
+                return `"${rawLocale}.${field}" exceeds ${TRANSLATION_VALUE_MAX_LENGTH} characters`;
+            }
+        }
+    }
+    return validateTranslationsLimits(normalizePatchKeys(input));
+}
+function normalizePatchKeys(patch) {
+    return applyPatch({}, patch) ?? {};
+}
+function applyPatch(base, patch) {
+    const result = { ...base };
+    for (const [rawLocale, entry] of Object.entries(patch)) {
+        const locale = normalizeLocale(rawLocale);
+        if (locale === null)
+            continue;
+        if (entry === null) {
+            delete result[locale];
+            continue;
+        }
+        const fields = {};
+        for (const [field, value] of Object.entries(entry)) {
+            if (typeof value === 'string' && value.length > 0)
+                fields[field] = value;
+        }
+        if (Object.keys(fields).length > 0)
+            result[locale] = fields;
+        else
+            delete result[locale];
+    }
+    return Object.keys(result).length > 0 ? result : null;
+}
+/** Applies a validated patch to the stored map; returns null when nothing remains. */
+function mergeTranslations(existing, patch) {
+    return applyPatch(existing ?? {}, patch);
+}
+/** Client-side clean-up of an edited map: trims values, drops blank ones and locales left without text, normalizes locale keys. */
+function cleanTranslations(map) {
+    const result = {};
+    for (const [rawLocale, fields] of Object.entries(map ?? {})) {
+        const locale = normalizeLocale(rawLocale);
+        if (locale === null)
+            continue;
+        const kept = {};
+        for (const [field, value] of Object.entries(fields ?? {})) {
+            const text = typeof value === 'string' ? value.trim() : '';
+            if (text.length > 0)
+                kept[field] = text;
+        }
+        if (Object.keys(kept).length > 0)
+            result[locale] = kept;
+    }
+    return result;
+}
+const sameFields = (a, b) => {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every(key => a[key] === b[key]);
+};
+/**
+ * Write payload for editing: a changed locale replaces that locale, a removed one is `null`.
+ * Returns `undefined` when nothing changed, so the field can be omitted and stored translations stay untouched.
+ * `mergeTranslations(original, patch)` yields `cleanTranslations(current)`.
+ */
+function buildTranslationsPatch(original, current) {
+    const before = cleanTranslations(original);
+    const after = cleanTranslations(current);
+    const patch = {};
+    for (const [locale, fields] of Object.entries(after)) {
+        if (!before[locale] || !sameFields(before[locale], fields))
+            patch[locale] = fields;
+    }
+    for (const locale of Object.keys(before)) {
+        if (!after[locale])
+            patch[locale] = null;
+    }
+    return Object.keys(patch).length > 0 ? patch : undefined;
+}
+/** Resolves the given translatable fields of a model for `locale`; base text when none applies. */
+function localizeFields(model, locale, fields) {
+    const result = {};
+    for (const field of fields) {
+        result[field] = (locale
+            ? resolveTranslation(model.translations, locale, field, (model[field] ?? null))
+            : model[field]);
+    }
+    return result;
+}
+/** Restricts a translations map to `fields`; locales left empty are dropped. Null when nothing remains. */
+function pickTranslationFields(map, fields) {
+    if (!map)
+        return null;
+    const result = {};
+    for (const [locale, entry] of Object.entries(map)) {
+        const picked = {};
+        for (const field of fields) {
+            if (hasOwn(entry, field) && typeof entry[field] === 'string')
+                picked[field] = entry[field];
+        }
+        if (Object.keys(picked).length > 0)
+            result[locale] = picked;
+    }
+    return Object.keys(result).length > 0 ? result : null;
+}
+/**
+ * Translations for a row that inherits unset fields from a template: each field's translations
+ * come from the same source as its base value (the row when it sets the field, otherwise the template).
+ */
+function inheritTranslations(row, template, fields) {
+    const fromRow = fields.filter(field => !template || row[field] != null);
+    const fromTemplate = fields.filter(field => !!template && row[field] == null);
+    const merged = {};
+    for (const [source, picked] of [
+        [row.translations, fromRow],
+        [template?.translations, fromTemplate],
+    ]) {
+        for (const [locale, entry] of Object.entries(pickTranslationFields(source, picked) ?? {})) {
+            merged[locale] = { ...merged[locale], ...entry };
+        }
+    }
+    return Object.keys(merged).length > 0 ? merged : null;
+}
+
 /**
  * Built-in user profile fields that can be required for redemptions.
  * These are a subset of UserModelField - excludes 'id' and 'identifierEmail'
@@ -3835,6 +4286,7 @@ const EntityTypes = {
     FILE: 'file',
     JWKS: 'jwks',
     PROJECT: 'project',
+    EVENTS: 'events',
 };
 /**
  * Error-specific domains (extends EntityTypes)
@@ -3859,6 +4311,68 @@ const AuditEntityTypes = {
     ...EntityTypes,
 };
 
+/**
+ * Canonical external event-type strings — the `type` field consumers see in
+ * delivered envelopes.  Composed from {@link EntityTypes} so domain names stay
+ * DRY.  Add a new entry here first; the events module registry then decides
+ * scope and whether to persist it.
+ *
+ * Convention: `<domain>.<verb>` in lowercase dot-notation.
+ */
+const ExternalEventType = {
+    // Users
+    UserCreated: `${EntityTypes.USER}.created`,
+    UserUpdated: `${EntityTypes.USER}.updated`,
+    // Transactions
+    TransactionCreated: `${EntityTypes.TRANSACTION}.created`,
+    TransactionMintSucceeded: `${EntityTypes.TRANSACTION}.mint_succeeded`,
+    TransactionBurnSucceeded: `${EntityTypes.TRANSACTION}.burn_succeeded`,
+    TransactionTransferSucceeded: `${EntityTypes.TRANSACTION}.transfer_succeeded`,
+    // Campaigns
+    CampaignCreated: `${EntityTypes.CAMPAIGN}.created`,
+    CampaignUpdated: `${EntityTypes.CAMPAIGN}.updated`,
+    CampaignClaimed: `${EntityTypes.CAMPAIGN}.claimed`,
+    CampaignClaimFailed: `${EntityTypes.CAMPAIGN}.claim_failed`,
+    // Redemptions
+    RedemptionCreated: `${EntityTypes.REDEMPTION}.created`,
+    RedemptionUpdated: `${EntityTypes.REDEMPTION}.updated`,
+    RedemptionRedeemed: `${EntityTypes.REDEMPTION}.redeemed`,
+    RedemptionRedeemFailed: `${EntityTypes.REDEMPTION}.redeem_failed`,
+    // Businesses
+    BusinessCreated: `${EntityTypes.BUSINESS}.created`,
+    BusinessUpdated: `${EntityTypes.BUSINESS}.updated`,
+    BusinessApproved: `${EntityTypes.BUSINESS}.approved`,
+    BusinessRejected: `${EntityTypes.BUSINESS}.rejected`,
+    // Campaigns (approval)
+    CampaignApproved: `${EntityTypes.CAMPAIGN}.approved`,
+    CampaignRejected: `${EntityTypes.CAMPAIGN}.rejected`,
+    // Token metadata (approval)
+    TokenMetadataApproved: `${EntityTypes.TOKEN_METADATA}.approved`,
+    TokenMetadataRejected: `${EntityTypes.TOKEN_METADATA}.rejected`,
+    // Redemptions (approval)
+    RedemptionApproved: `${EntityTypes.REDEMPTION}.approved`,
+    RedemptionRejected: `${EntityTypes.REDEMPTION}.rejected`,
+    // Bookings
+    BookingCreated: `${EntityTypes.BOOKING}.created`,
+    BookingUpdated: `${EntityTypes.BOOKING}.updated`,
+    // Token metadata
+    TokenMetadataCreated: `${EntityTypes.TOKEN_METADATA}.created`,
+    TokenMetadataUpdated: `${EntityTypes.TOKEN_METADATA}.updated`,
+    // Auth
+    MagicLinkSent: `${EntityTypes.USER}.magic_link_sent`,
+};
+
+/**
+ * Approval status for entities that may require tenant admin approval before becoming active.
+ * Controlled by tenant.approvalSettings per-entity-type flags.
+ */
+exports.ApprovalStatus = void 0;
+(function (ApprovalStatus) {
+    ApprovalStatus["PENDING_APPROVAL"] = "pending_approval";
+    ApprovalStatus["APPROVED"] = "approved";
+    ApprovalStatus["REJECTED"] = "rejected";
+})(exports.ApprovalStatus || (exports.ApprovalStatus = {}));
+
 /**
  * Error categories for classification and handling
  *
@@ -3901,6 +4415,33 @@ exports.ErrorCategory = void 0;
     ErrorCategory["UNKNOWN"] = "UNKNOWN";
 })(exports.ErrorCategory || (exports.ErrorCategory = {}));
 
+/**
+ * Describes the payment/redemption mechanism from the user's perspective.
+ * Computed at read time in the mapper — never stored.
+ *
+ * Use this for frontend rendering decisions (card labels, CTAs, progress UI)
+ * instead of inspecting creditTokenAmount + priceTokenUnits shape directly.
+ */
+exports.RedemptionMechanism = void 0;
+(function (RedemptionMechanism) {
+    /** No payment required — redemption is free. */
+    RedemptionMechanism["FREE"] = "FREE";
+    /** User pays with credit tokens only (creditTokenAmount > 0, no priceTokenUnits). */
+    RedemptionMechanism["CREDIT"] = "CREDIT";
+    /**
+     * User transfers ERC20 tokens as payment (priceTokenUnits with ERC20 token type).
+     * Distinct from CREDIT: uses an on-chain token transfer, not the platform credit balance.
+     */
+    RedemptionMechanism["TOKEN_PAY"] = "TOKEN_PAY";
+    /**
+     * User burns/transfers ERC1155 or ERC721 tokens as payment.
+     * Typical use case: stamp card redemption (collect N stamps → redeem reward).
+     */
+    RedemptionMechanism["TOKEN_BURN"] = "TOKEN_BURN";
+    /** User pays with both creditTokenAmount AND priceTokenUnits. */
+    RedemptionMechanism["MIXED"] = "MIXED";
+})(exports.RedemptionMechanism || (exports.RedemptionMechanism = {}));
+
 /**
  * PERS WS-Relay Shared Types
  *
@@ -3956,6 +4497,12 @@ function isErrorMessage(msg) {
 function isPingMessage(msg) {
     return msg.type === 'ping';
 }
+/**
+ * Type guard for notification.pending messages
+ */
+function isNotificationPendingMessage(msg) {
+    return msg.type === 'notification.pending';
+}
 
 /**
  * Check if a string matches UUID format
@@ -3974,6 +4521,10 @@ const NativeTokenTypes = {
     ERC1155: 'ERC1155',
     ERC721: 'ERC721'
 };
+/** Returns true for ERC721 and ERC1155 token types, false for ERC20. */
+function isNftTokenType(type) {
+    return type === NativeTokenTypes.ERC721 || type === NativeTokenTypes.ERC1155;
+}
 
 const ANALYTICS_METRIC_TYPES = ['count', 'sum', 'avg', 'min', 'max'];
 const ANALYTICS_GROUP_BY_TYPES = ['month', 'week', 'day', 'year', 'quarter'];
@@ -4021,6 +4572,7 @@ const Domains = {
     WEBHOOK: 'webhook',
     EMAIL: 'email',
     AUDIT: 'audit',
+    NOTIFICATION: 'notification',
 };
 
 /**
@@ -4069,7 +4621,8 @@ const VALID_CAMPAIGN_RELATIONS = [
     'triggerSources',
     'businesses',
     'claimCount',
-    'ownerBusiness'
+    'ownerBusiness',
+    'translations'
 ];
 /**
  * Type guard to validate campaign include relation at runtime
@@ -4110,7 +4663,8 @@ const VALID_REDEMPTION_RELATIONS = [
     'redeemCount',
     'ownerBusiness',
     'requiredUserInfo',
-    'booking'
+    'booking',
+    'translations'
 ];
 /**
  * Type guard to validate redemption include relation at runtime
@@ -4156,6 +4710,13 @@ function isValidBusinessMembershipRelation(value) {
     return VALID_BUSINESS_MEMBERSHIP_RELATIONS.includes(value);
 }
 
+const VALID_BUSINESS_RELATIONS = [
+    'translations'
+];
+function isValidBusinessRelation(value) {
+    return VALID_BUSINESS_RELATIONS.includes(value);
+}
+
 /**
  * Valid include relations for User endpoints.
  * These relations can be requested via ?include=status,balances query parameter.
@@ -4176,7 +4737,8 @@ const VALID_TOKEN_METADATA_RELATIONS = [
     'ownerBusiness',
     'mintCount',
     'burnCount',
-    'token'
+    'token',
+    'translations'
 ];
 /**
  * Type guard to validate token metadata include relation at runtime
@@ -4280,7 +4842,7 @@ function computeBookingStatus(checkInDate, checkOutDate, referenceDate = new Dat
     checkOut.setHours(0, 0, 0, 0);
     // Defensive validation: checkOut must be after checkIn
     // This catches invalid data from frontend or data integrity issues
-    if (checkOut <= checkIn) {
+    if (checkOut < checkIn) {
         throw new Error(`Invalid booking dates: checkOut (${checkOut.toISOString()}) must be after checkIn (${checkIn.toISOString()})`);
     }
     // Checkout day itself counts as still active (guest there until end of day)
@@ -4498,28 +5060,28 @@ function parseUserAgentForPlatform(userAgent) {
     // Detect OS and device type
     if (/iPhone|iPod/i.test(ua)) {
         platform.os = 'iOS';
-        const match = ua.match(/OS (\d+)[_\.](\d+)/);
+        const match = ua.match(/OS (\d+)[_.](\d+)/);
         if (match)
             platform.osVersion = `${match[1]}.${match[2]}`;
         platform.deviceType = 'phone';
     }
     else if (/iPad/i.test(ua)) {
         platform.os = 'iOS';
-        const match = ua.match(/OS (\d+)[_\.](\d+)/);
+        const match = ua.match(/OS (\d+)[_.](\d+)/);
         if (match)
             platform.osVersion = `${match[1]}.${match[2]}`;
         platform.deviceType = 'tablet';
     }
     else if (/Android/i.test(ua)) {
         platform.os = 'Android';
-        const match = ua.match(/Android ([\d\.]+)/);
+        const match = ua.match(/Android ([\d.]+)/);
         if (match)
             platform.osVersion = match[1];
         platform.deviceType = /Mobile/i.test(ua) ? 'phone' : 'tablet';
     }
     else if (/Windows NT/i.test(ua)) {
         platform.os = 'Windows';
-        const match = ua.match(/Windows NT ([\d\.]+)/);
+        const match = ua.match(/Windows NT ([\d.]+)/);
         if (match)
             platform.osVersion = match[1];
         platform.deviceType = 'desktop';
@@ -4538,31 +5100,31 @@ function parseUserAgentForPlatform(userAgent) {
     // Detect browser (web channel)
     if (/Edg\//i.test(ua)) {
         platform.browser = 'Edge';
-        const match = ua.match(/Edg\/([\d\.]+)/);
+        const match = ua.match(/Edg\/([\d.]+)/);
         if (match)
             platform.browserVersion = match[1];
     }
     else if (/Chrome\//i.test(ua) && !/Edg/i.test(ua)) {
         platform.browser = 'Chrome';
-        const match = ua.match(/Chrome\/([\d\.]+)/);
+        const match = ua.match(/Chrome\/([\d.]+)/);
         if (match)
             platform.browserVersion = match[1];
     }
     else if (/Safari\//i.test(ua) && !/Chrome/i.test(ua)) {
         platform.browser = 'Safari';
-        const match = ua.match(/Version\/([\d\.]+)/);
+        const match = ua.match(/Version\/([\d.]+)/);
         if (match)
             platform.browserVersion = match[1];
     }
     else if (/Firefox\//i.test(ua)) {
         platform.browser = 'Firefox';
-        const match = ua.match(/Firefox\/([\d\.]+)/);
+        const match = ua.match(/Firefox\/([\d.]+)/);
         if (match)
             platform.browserVersion = match[1];
     }
     else if (/Opera|OPR\//i.test(ua)) {
         platform.browser = 'Opera';
-        const match = ua.match(/(?:Opera|OPR)\/([\d\.]+)/);
+        const match = ua.match(/(?:Opera|OPR)\/([\d.]+)/);
         if (match)
             platform.browserVersion = match[1];
     }
@@ -4649,6 +5211,28 @@ function parseUtmParams(url) {
     return params;
 }
 
+/** Default page when none is specified. */
+const DEFAULT_PAGE = 1;
+/** Default page size when none is specified. */
+const DEFAULT_PAGE_SIZE = 50;
+/**
+ * Build a URLSearchParams object from pagination options.
+ *
+ * Always includes page/limit so the server always receives explicit values.
+ * Uses `??` (not `||`) so an explicit `page: 0` / `limit: 0` is preserved
+ * rather than silently replaced by the default.
+ */
+function buildPaginationParams(options) {
+    const params = new URLSearchParams();
+    params.set('page', String(options?.page ?? DEFAULT_PAGE));
+    params.set('limit', String(options?.limit ?? DEFAULT_PAGE_SIZE));
+    if (options?.sortBy)
+        params.set('sortBy', options.sortBy);
+    if (options?.sortOrder)
+        params.set('sortOrder', options.sortOrder);
+    return params;
+}
+
 /**
  * Analytics Constants
  *
@@ -4777,6 +5361,53 @@ function isSupportedImageFormat(extension) {
     return IMAGE_CDN_SUPPORTED_FORMATS.includes(extension.toLowerCase());
 }
 
+/**
+ * Chain RPC Permissions
+ *
+ * Canonical permission sets for BLOCKCHAIN_READER_JWT / BLOCKCHAIN_WRITER_JWT tokens
+ * issued to authenticate against private chain RPC endpoints (e.g. PERS Besu).
+ * Single source of truth shared between Web3ChainDomainService (NestJS app) and any
+ * raw, no-NestJS Lambda that needs to self-issue the same token (e.g.
+ * serverless-functions/infrastructure/chain-provider.ts) — keeps both in sync instead
+ * of letting a hand-picked subset drift and silently 401 on RPC calls it never
+ * anticipated needing.
+ */
+const CHAIN_READ_PERMISSIONS = [
+    'eth:call',
+    'eth:chainId',
+    'eth:getTransactionCount',
+    'eth:estimateGas',
+    'eth:gasPrice',
+    'eth:getBalance',
+    'eth:getBlockByNumber',
+    'eth:getBlockByHash',
+    'eth:getBlockTransactionCountByHash',
+    'eth:getBlockTransactionCountByNumber',
+    'eth:getCode',
+    'eth:getTransactionByBlockHashAndIndex',
+    'eth:getTransactionByBlockNumberAndIndex',
+    'eth:getTransactionByHash',
+    'eth:getTransactionReceipt',
+    'eth:subscribe',
+    'eth:unsubscribe',
+];
+const CHAIN_WRITE_PERMISSIONS = [
+    'eth:*',
+];
+
+const CUSTOM_FIELD_TRANSLATABLE_FIELDS = ['label', 'description'];
+const USER_STATUS_TYPE_TRANSLATABLE_FIELDS = ['name', 'description'];
+const BUSINESS_TYPE_TRANSLATABLE_FIELDS = ['name', 'description'];
+const BUSINESS_TRANSLATABLE_FIELDS = ['displayName', 'description', 'shortDescription'];
+const TOKEN_METADATA_TRANSLATABLE_FIELDS = ['name', 'description'];
+const CAMPAIGN_TRIGGER_TRANSLATABLE_FIELDS = ['name', 'description', 'terms'];
+const TRIGGER_SOURCE_TRANSLATABLE_FIELDS = ['name', 'description'];
+const CAMPAIGN_TRANSLATABLE_FIELDS = ['name', 'description'];
+const REDEMPTION_TYPE_TRANSLATABLE_FIELDS = ['name', 'description'];
+const REDEMPTION_TRANSLATABLE_FIELDS = ['name', 'description', 'terms'];
+const TENANT_TRANSLATABLE_FIELDS = ['projectDescription'];
+const PURCHASE_TOKEN_TRANSLATABLE_FIELDS = ['description'];
+
 /**
  * Chain Data Types
  *
@@ -4850,6 +5481,8 @@ const CommonErrorCodes = {
     // Business domain
     BUSINESS_NOT_FOUND: 'BUSINESS_NOT_FOUND',
     BUSINESS_NOT_MINTER: 'BUSINESS_NOT_MINTER',
+    BUSINESS_DISPLAY_NAME_ALREADY_EXISTS: 'BUSINESS_DISPLAY_NAME_ALREADY_EXISTS',
+    BUSINESS_NOT_APPROVED: 'BUSINESS_NOT_APPROVED',
     // Membership domain
     MEMBERSHIP_NOT_FOUND: 'MEMBERSHIP_NOT_FOUND',
     MEMBERSHIP_ALREADY_EXISTS: 'MEMBERSHIP_ALREADY_EXISTS',
@@ -4867,6 +5500,7 @@ const CommonErrorCodes = {
     CAMPAIGN_BUSINESS_REQUIRED: 'CAMPAIGN_BUSINESS_REQUIRED',
     CAMPAIGN_CONDITION_NOT_MET: 'CAMPAIGN_CONDITION_NOT_MET',
     CAMPAIGN_ALREADY_CLAIMED: 'CAMPAIGN_ALREADY_CLAIMED',
+    CAMPAIGN_CLAIM_ALREADY_PROCESSING: 'CAMPAIGN_CLAIM_ALREADY_PROCESSING',
     CAMPAIGN_NO_TRIGGER: 'CAMPAIGN_NO_TRIGGER',
     CAMPAIGN_LOCATION_REQUIRED: 'CAMPAIGN_LOCATION_REQUIRED',
     CAMPAIGN_DISTANCE_EXCEEDED: 'CAMPAIGN_DISTANCE_EXCEEDED',
@@ -4883,6 +5517,8 @@ const CommonErrorCodes = {
     LOCATION_VERIFICATION_REQUIRED: 'LOCATION_VERIFICATION_REQUIRED',
     // Trigger domain
     TRIGGER_NOT_FOUND: 'TRIGGER_NOT_FOUND',
+    // Notification domain
+    NOTIFICATION_NOT_FOUND: 'NOTIFICATION_NOT_FOUND',
     // Trigger Source domain
     TRIGGER_SOURCE_NOT_FOUND: 'TRIGGER_SOURCE_NOT_FOUND',
     // Generic domain errors
@@ -4896,10 +5532,15 @@ const CommonErrorCodes = {
     EXTERNAL_SERVICE_ERROR: 'EXTERNAL_SERVICE_ERROR',
     AUTHENTICATION_REQUIRED: 'AUTHENTICATION_REQUIRED',
     AUTHORIZATION_FAILED: 'AUTHORIZATION_FAILED',
+    NO_BUSINESS_ACCESS: 'NO_BUSINESS_ACCESS',
+    USER_INACTIVE: 'USER_INACTIVE',
     CONFIGURATION_MISSING: 'CONFIGURATION_MISSING',
     // Redemption domain
     USER_STATUS_RESTRICTED: 'USER_STATUS_RESTRICTED',
     REDEMPTION_ALREADY_PROCESSING: 'REDEMPTION_ALREADY_PROCESSING',
+    REDEMPTION_NOT_ACTIVE: 'REDEMPTION_NOT_ACTIVE',
+    REDEMPTION_ENDED: 'REDEMPTION_ENDED',
+    REDEMPTION_NOT_STARTED: 'REDEMPTION_NOT_STARTED',
     MAX_REDEMPTION: 'MAX_REDEMPTION',
     USER_LIMIT: 'USER_LIMIT',
     REQUIRED_FIELDS_MISSING: 'REQUIRED_FIELDS_MISSING',
@@ -4931,6 +5572,8 @@ const CommonErrorCodes = {
     WEBHOOK_SIGNATURE_INVALID: 'WEBHOOK_SIGNATURE_INVALID',
     WEBHOOK_FORWARD_FAILED: 'WEBHOOK_FORWARD_FAILED',
     WEBHOOK_TIMEOUT: 'WEBHOOK_TIMEOUT',
+    // Events domain
+    EVENT_SUBSCRIPTION_NOT_FOUND: 'EVENT_SUBSCRIPTION_NOT_FOUND',
     // Conflict errors (409)
     RESOURCE_CONFLICT: 'RESOURCE_CONFLICT',
     CONCURRENT_MODIFICATION: 'CONCURRENT_MODIFICATION',
@@ -5525,39 +6168,11 @@ const CacheTTL = {
     PROVIDER: 60 * 60 * 1000, // 1 hour - Provider connections with auth
 };
 
-// ==========================================
-// UTILITY FUNCTIONS
-// ==========================================
-/**
- * Helper to build pagination query params with defaults
- * Ensures pagination params are always included in API requests
- *
- * @param options - Pagination options (optional)
- * @returns URLSearchParams with page and limit always set
- *
- * @example
- * ```typescript
- * async getItems(options?: PaginationOptions): Promise<PaginatedResponseDTO<ItemDTO>> {
- *   const params = buildPaginationParams(options);
- *   // params always includes: page=1&limit=50 (or custom values)
- *
- *   if (options?.sortBy) params.set('sortBy', options.sortBy);
- *   if (options?.sortOrder) params.set('sortOrder', options.sortOrder);
- *
- *   return this.apiClient.get(`/items?${params.toString()}`);
- * }
- * ```
- */
-function buildPaginationParams(options) {
-    const params = new URLSearchParams();
-    // Always include pagination params (defaults)
-    params.set('page', String(options?.page ?? 1));
-    params.set('limit', String(options?.limit ?? 50));
-    if (options?.sortBy)
-        params.set('sortBy', options.sortBy);
-    if (options?.sortOrder)
-        params.set('sortOrder', options.sortOrder);
-    return params;
+// Re-export pagination primitives from @explorins/pers-shared (single source of truth)
+/** Sets the comma-separated `include` query parameter when there is anything to include. */
+function setIncludeParam(params, include) {
+    if (include?.length)
+        params.set('include', include.join(','));
 }
 /**
  * Type guard to check if response is paginated
@@ -5676,7 +6291,7 @@ function normalizeToPaginated(response) {
  * );
  * ```
  */
-async function fetchAllPages(fetchFn, limit = 50, maxPages = 100) {
+async function fetchAllPages(fetchFn, limit = DEFAULT_PAGE_SIZE, maxPages = 100) {
     const allItems = [];
     let page = 1;
     let hasMore = true;
@@ -5728,6 +6343,13 @@ class UserApi {
         const response = await this.apiClient.get(url);
         return normalizeToPaginated(response);
     }
+    /**
+     * PUBLIC: Get a single user's public profile by ID
+     * Uses RESTful /users/public/:id endpoint
+     */
+    async getPublicProfileById(id) {
+        return this.apiClient.get(`${this.basePath}/public/${id}`);
+    }
     // ==========================================
     // AUTHENTICATED OPERATIONS
     // ==========================================
@@ -5936,6 +6558,12 @@ class UserService {
     async getAllUsersPublicProfiles(filter = null, options) {
         return this.userApi.getAllUsersPublicProfiles(filter, options);
     }
+    /**
+     * PUBLIC: Get a single user's public profile by ID
+     */
+    async getPublicProfileById(id) {
+        return this.userApi.getPublicProfileById(id);
+    }
     // ==========================================
     // AUTHENTICATED OPERATIONS
     // ==========================================
@@ -6067,6 +6695,7 @@ class UserStatusApi {
     async getRemoteUserStatusTypes(options) {
         try {
             const params = buildPaginationParams(options);
+            setIncludeParam(params, options?.include);
             const response = await this.apiClient.get(`${this.basePath}/status-types?${params.toString()}`);
             return normalizeToPaginated(response);
         }
@@ -6075,13 +6704,18 @@ class UserStatusApi {
             throw error;
         }
     }
+    /** PUBLIC: Get one user status type; `translations` adds the raw per-locale map (admin editing). */
+    async getRemoteUserStatusTypeById(id, include) {
+        const params = include?.length ? `?include=${include.join(',')}` : '';
+        return this.apiClient.get(`${this.basePath}/status-types/${id}${params}`);
+    }
     // ==========================================
     // AUTHENTICATED OPERATIONS
     // ==========================================
     /**
      * AUTH: Get earned user status for authenticated user
      * ✅ UPDATED: /user/auth/status → /users/me/status
-     * ✅ FIXED: Returns PaginatedResponseDTO<UserStatusTypeDTO> to match v2.0.0
+     * ✅ FIXED: Returns `PaginatedResponseDTO<UserStatusTypeDTO>` to match v2.0.0
      * Note: Uses silent fallback pattern from framework - returns empty paginated response on error
      */
     async getRemoteEarnedUserStatus(options) {
@@ -6163,6 +6797,9 @@ class UserStatusService {
     async getRemoteUserStatusTypes(options) {
         return this.userStatusApi.getRemoteUserStatusTypes(options);
     }
+    async getRemoteUserStatusTypeById(id, include) {
+        return this.userStatusApi.getRemoteUserStatusTypeById(id, include);
+    }
     // ==========================================
     // AUTHENTICATED OPERATIONS
     // ==========================================
@@ -6216,6 +6853,7 @@ function createUserStatusSDK(apiClient) {
         // ✅ FRAMEWORK ALIGNED: Only methods actually used by framework
         // Public methods
         getRemoteUserStatusTypes: (options) => userStatusService.getRemoteUserStatusTypes(options),
+        getRemoteUserStatusTypeById: (id, include) => userStatusService.getRemoteUserStatusTypeById(id, include),
         // Auth methods
         getRemoteEarnedUserStatus: (options) => userStatusService.getRemoteEarnedUserStatus(options),
         // Admin methods
@@ -6353,6 +6991,9 @@ class TokenApi {
         if (options?.search) {
             params.set('search', options.search);
         }
+        if (options?.approvalStatus) {
+            params.set('approvalStatus', options.approvalStatus);
+        }
         // Handle tags as string or array
         if (options?.tags) {
             const tagsArray = Array.isArray(options.tags) ? options.tags : [options.tags];
@@ -6374,6 +7015,15 @@ class TokenApi {
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
+    /**
+     * ADMIN/BUSINESS: Get one token metadata (a business can only read its own)
+     *
+     * @param include - Same relations as the list: `translations` adds the raw per-locale map (admin editing)
+     */
+    async getTokenMetadataById(metadataId, include) {
+        const params = include?.length ? `?include=${include.join(',')}` : '';
+        return this.apiClient.get(`${this.basePath}/metadata/${metadataId}${params}`);
+    }
     /**
      * ADMIN: Create new token
      */
@@ -6452,7 +7102,7 @@ class TokenApi {
         return this.apiClient.delete(`${this.basePath}/metadata/${metadataId}`);
     }
     // ==========================================
-    // 📊 CSV EXPORT
+    // 📊 CSV EXPORT
     // ==========================================
     /**
      * ADMIN: Export token metadata to CSV
@@ -6488,6 +7138,23 @@ class TokenApi {
         const url = `${this.basePath}/metadata/export/csv${queryString ? `?${queryString}` : ''}`;
         return this.apiClient.get(url, 'blob');
     }
+    // ==========================================
+    // ✅ APPROVAL WORKFLOW
+    // ==========================================
+    /**
+     * ADMIN: Approve a token metadata
+     *
+     * Approves token metadata that is pending approval, changing its status to 'approved'.
+     *
+     * Endpoint: PATCH /admin/token-metadata/:id/approve
+     * Auth: @TenantAdmin()
+     *
+     * @param tokenMetadataId - ID of the token metadata to approve
+     * @returns Updated token metadata with approval metadata
+     */
+    async setTokenMetadataApproval(tokenMetadataId, status, reason) {
+        return this.apiClient.patch(`/tokens/metadata/${tokenMetadataId}/approval`, { status, reason });
+    }
 }
 
 /**
@@ -6561,6 +7228,12 @@ class TokenService {
     async getTokenMetadata(options) {
         return this.tokenApi.getTokenMetadata(options);
     }
+    /**
+     * Get one token metadata by ID (admin/business), with the same include relations as the list
+     */
+    async getTokenMetadataById(metadataId, include) {
+        return this.tokenApi.getTokenMetadataById(metadataId, include);
+    }
     /**
      * Get rewards (ERC1155 token metadata) with filtering, pagination, and include relations
      *
@@ -6692,7 +7365,7 @@ class BusinessApi {
         this.businessTypesPath = '/businesses/types';
     }
     // ==========================================
-    // 🌐 BUSINESS TYPES MANAGEMENT
+    // 🌐 BUSINESS TYPES MANAGEMENT
     // ==========================================
     /**
      * Get all business types (project key required)
@@ -6705,9 +7378,15 @@ class BusinessApi {
      */
     async getBusinessTypes(options) {
         const params = buildPaginationParams(options);
+        setIncludeParam(params, options?.include);
         const response = await this.apiClient.get(`${this.businessTypesPath}?${params.toString()}`);
         return normalizeToPaginated(response);
     }
+    /** PUBLIC: Get one business type; `translations` adds the raw per-locale map (admin editing). */
+    async getBusinessTypeById(id, include) {
+        const params = include?.length ? `?include=${include.join(',')}` : '';
+        return this.apiClient.get(`${this.businessTypesPath}/${id}${params}`);
+    }
     /**
      * ADMIN: Create business type
      *
@@ -6736,7 +7415,7 @@ class BusinessApi {
         return this.apiClient.delete(`${this.businessTypesPath}/${id}`);
     }
     // ==========================================
-    // 🏢 BUSINESS MANAGEMENT
+    // 🏢 BUSINESS MANAGEMENT
     // ==========================================
     /**
      * Get current business info (business authentication required)
@@ -6786,12 +7465,15 @@ class BusinessApi {
      */
     async getBusinesses(options) {
         const params = buildPaginationParams(options);
+        setIncludeParam(params, options?.include);
         if (options?.active !== undefined) {
             params.set('active', String(options.active));
         }
         if (options?.search) {
             params.set('search', options.search);
         }
+        if (options?.approvalStatus)
+            params.set('approvalStatus', options.approvalStatus);
         // Support single tag or array of tags (multiple ?tags=a&tags=b)
         if (options?.tags) {
             const tagsArray = Array.isArray(options.tags) ? options.tags : [options.tags];
@@ -6801,6 +7483,12 @@ class BusinessApi {
         if (options?.sanitize) {
             params.set('sanitize', options.sanitize);
         }
+        // Batch lookup by id: one comma-separated param keeps the URL short for large id lists
+        if (options?.ids) {
+            const ids = Array.isArray(options.ids) ? options.ids : [options.ids];
+            if (ids.length > 0)
+                params.set('ids', ids.join(','));
+        }
         if (options?.businessTypeId !== undefined) {
             params.set('businessTypeId', String(options.businessTypeId));
         }
@@ -6820,17 +7508,74 @@ class BusinessApi {
         if (options?.district) {
             params.set('district', options.district);
         }
+        // Geographic radius search parameters
+        if (options?.latitude !== undefined) {
+            params.set('latitude', String(options.latitude));
+        }
+        if (options?.longitude !== undefined) {
+            params.set('longitude', String(options.longitude));
+        }
+        if (options?.radiusMeters !== undefined) {
+            params.set('radiusMeters', String(options.radiusMeters));
+        }
+        // Capability flag filters (admin only - ignored by non-admin callers server-side)
+        if (options?.canMintToken !== undefined) {
+            params.set('canMintToken', String(options.canMintToken));
+        }
+        if (options?.canChargeToken !== undefined) {
+            params.set('canChargeToken', String(options.canChargeToken));
+        }
+        if (options?.canManageUsers !== undefined) {
+            params.set('canManageUsers', String(options.canManageUsers));
+        }
+        if (options?.canReceiveDonation !== undefined) {
+            params.set('canReceiveDonation', String(options.canReceiveDonation));
+        }
         const response = await this.apiClient.get(`${this.basePath}?${params.toString()}`);
         return normalizeToPaginated(response);
     }
+    /**
+     * Get the distinct list of cities that have at least one business, for populating
+     * city filter options before calling `getBusinesses({ city })`. Each option includes
+     * `country`/`countryCode` so same-named cities in different countries can be disambiguated.
+     *
+     * Endpoint: GET /businesses/cities
+     * Auth: @ApiSecurity('projectKey') (enhanced with role-based filtering, same as getBusinesses)
+     *
+     * @example
+     * ```typescript
+     * const cities = await businessApi.getBusinessCities();
+     * // [{ city: 'Doha', country: 'Qatar', countryCode: 'QA' }, ...]
+     *
+     * const citiesInQatar = await businessApi.getBusinessCities({ countryCode: 'QA' });
+     * ```
+     */
+    async getBusinessCities(options) {
+        const params = new URLSearchParams();
+        if (options?.active !== undefined)
+            params.set('active', String(options.active));
+        if (options?.approvalStatus)
+            params.set('approvalStatus', options.approvalStatus);
+        if (options?.countryCode)
+            params.set('countryCode', options.countryCode);
+        if (options?.country)
+            params.set('country', options.country);
+        if (options?.businessTypeId !== undefined)
+            params.set('businessTypeId', String(options.businessTypeId));
+        const query = params.toString();
+        return this.apiClient.get(`${this.basePath}/cities${query ? `?${query}` : ''}`);
+    }
     /**
      * Get business by ID
      *
      * Endpoint: GET /businesses/{id}
      * Auth: @ApiSecurity('projectKey')
      */
-    async getBusinessById(businessId) {
-        return this.apiClient.get(`${this.basePath}/${businessId}`);
+    async getBusinessById(businessId, include) {
+        const params = new URLSearchParams();
+        setIncludeParam(params, include);
+        const query = params.toString();
+        return this.apiClient.get(`${this.basePath}/${businessId}${query ? `?${query}` : ''}`);
     }
     /**
      * Get business by account address
@@ -6842,14 +7587,14 @@ class BusinessApi {
         return this.apiClient.get(`${this.basePath}/account/${accountAddress}`);
     }
     // ==========================================
-    // 🔧 ADMIN OPERATIONS
+    // 🔧 ADMIN OPERATIONS
     // ==========================================
     /**
      * ADMIN: Create business
      *
      * Endpoint: POST /businesses
      * Auth: @TenantAdmin()
-     * Returns: BusinessApiKeyDTO | BusinessTokenBalancesDTO
+     * Returns: BusinessApiKeyDTO
      */
     async createBusiness(dto) {
         return this.apiClient.post(this.basePath, dto);
@@ -6904,7 +7649,7 @@ class BusinessApi {
     //   return this.apiClient.put<string>(`${this.basePath}/${id}/api-key`, {});
     // }
     // ==========================================
-    // 📊 CSV EXPORT
+    // 📊 CSV EXPORT
     // ==========================================
     /**
      * ADMIN: Export businesses to CSV
@@ -6930,6 +7675,31 @@ class BusinessApi {
      * });
      * ```
      */
+    // ==========================================
+    // ✅ APPROVAL WORKFLOW
+    // ==========================================
+    /**
+     * ADMIN: Approve a business
+     *
+     * Approves a business that is pending approval, changing its status to 'approved'.
+     * Only businesses with approval status 'pending_approval' can be approved.
+     *
+     * Endpoint: PATCH /admin/businesses/:id/approve
+     * Auth: @TenantAdmin()
+     *
+     * @param businessId - ID of the business to approve
+     * @returns Updated business with approval metadata
+     *
+     * @example
+     * `	ypescript
+     * const approvedBusiness = await businessApi.approveBusiness('business-123');
+     * console.log('Approved by:', approvedBusiness.approval?.approvedBy);
+     * console.log('Approved at:', approvedBusiness.approval?.approvedAt);
+     * `
+     */
+    async setBusinessApproval(businessId, status, reason) {
+        return this.apiClient.patch(`/businesses/${businessId}/approval`, { status, reason });
+    }
     async exportCSV(options) {
         const params = new URLSearchParams();
         if (options?.dateFrom)
@@ -7202,11 +7972,21 @@ class BusinessService {
     async getBusinessTypes(options) {
         return this.businessApi.getBusinessTypes(options);
     }
+    async getBusinessTypeById(id, include) {
+        return this.businessApi.getBusinessTypeById(id, include);
+    }
     /**
      * Get business by ID
      */
-    async getBusinessById(businessId) {
-        return this.businessApi.getBusinessById(businessId);
+    async getBusinessById(businessId, include) {
+        return this.businessApi.getBusinessById(businessId, include);
+    }
+    /**
+     * Get the distinct list of cities that have at least one business, for populating
+     * city filter options before calling `getBusinesses({ city })`.
+     */
+    async getBusinessCities(options) {
+        return this.businessApi.getBusinessCities(options);
     }
     /**
      * Get business by account address
@@ -7237,11 +8017,18 @@ class BusinessService {
     async getBusinesses(options) {
         return this.businessApi.getBusinesses(options);
     }
+    /**
+     * ADMIN: Create business with full DTO
+     */
+    async createBusiness(dto) {
+        return this.businessApi.createBusiness(dto);
+    }
     /**
      * ADMIN: Create business by display name
+     * @deprecated Use createBusiness(dto) for full control
      */
     async createBusinessByDisplayName(displayName) {
-        return this.businessApi.createBusinessByDisplayName(displayName);
+        return this.businessApi.createBusiness({ displayName });
     }
     /**
      * ADMIN: Update business
@@ -7573,36 +8360,32 @@ class CampaignApi {
      * ```
      */
     async getCampaigns(options) {
-        const params = [];
-        // Always include pagination params to ensure paginated response
-        params.push(`page=${options?.page || 1}`);
-        params.push(`limit=${options?.limit || 50}`);
+        // Always include pagination params (page/limit, plus sortBy/sortOrder) to ensure a paginated response
+        const params = buildPaginationParams(options);
         if (options?.active !== undefined)
-            params.push(`active=${options.active}`);
+            params.set('active', String(options.active));
         // Support single tag or array of tags (multiple ?tags=a&tags=b)
         if (options?.tags) {
             const tagsArray = Array.isArray(options.tags) ? options.tags : [options.tags];
-            tagsArray.forEach(t => params.push(`tags=${encodeURIComponent(t)}`));
+            tagsArray.forEach(t => params.append('tags', t));
         }
         if (options?.businessId)
-            params.push(`businessId=${encodeURIComponent(options.businessId)}`);
+            params.set('businessId', options.businessId);
+        if (options?.ownerBusinessId)
+            params.set('ownerBusinessId', options.ownerBusinessId);
+        if (options?.approvalStatus)
+            params.set('approvalStatus', options.approvalStatus);
+        if (options?.status)
+            params.set('status', [options.status].flat().join(','));
         if (options?.search)
-            params.push(`search=${encodeURIComponent(options.search)}`);
-        if (options?.startDate) {
-            const dateStr = options.startDate instanceof Date ? options.startDate.toISOString() : options.startDate;
-            params.push(`startDate=${encodeURIComponent(dateStr)}`);
-        }
-        if (options?.endDate) {
-            const dateStr = options.endDate instanceof Date ? options.endDate.toISOString() : options.endDate;
-            params.push(`endDate=${encodeURIComponent(dateStr)}`);
-        }
-        if (options?.sortBy)
-            params.push(`sortBy=${options.sortBy}`);
-        if (options?.sortOrder)
-            params.push(`sortOrder=${options.sortOrder}`);
+            params.set('search', options.search);
+        if (options?.startDate)
+            params.set('startDate', options.startDate);
+        if (options?.endDate)
+            params.set('endDate', options.endDate);
         if (options?.include?.length)
-            params.push(`include=${options.include.join(',')}`);
-        return this.apiClient.get(`/campaigns?${params.join('&')}`);
+            params.set('include', options.include.join(','));
+        return this.apiClient.get(`/campaigns?${params.toString()}`);
     }
     /**
      * PUBLIC: Get campaign by ID
@@ -7869,6 +8652,10 @@ class CampaignApi {
             params.set('userId', filters.userId);
         if (filters?.businessId)
             params.set('businessId', filters.businessId);
+        if (filters?.triggerType)
+            params.set('triggerType', filters.triggerType);
+        if (filters?.status)
+            params.set('status', filters.status);
         if (filters?.dateFrom)
             params.set('dateFrom', filters.dateFrom instanceof Date ? filters.dateFrom.toISOString() : filters.dateFrom);
         if (filters?.dateTo)
@@ -7963,6 +8750,23 @@ class CampaignApi {
         const url = `/campaigns/claims/export/csv${queryString ? `?${queryString}` : ''}`;
         return this.apiClient.get(url, 'blob');
     }
+    // ==========================================
+    // ✅ APPROVAL WORKFLOW
+    // ==========================================
+    /**
+     * ADMIN: Approve a campaign
+     *
+     * Approves a campaign that is pending approval, changing its status to 'approved'.
+     *
+     * Endpoint: PATCH /admin/campaigns/:id/approve
+     * Auth: @TenantAdmin()
+     *
+     * @param campaignId - ID of the campaign to approve
+     * @returns Updated campaign with approval metadata
+     */
+    async setCampaignApproval(campaignId, status, reason) {
+        return this.apiClient.patch(`/campaigns/${campaignId}/approval`, { status, reason });
+    }
 }
 
 /**
@@ -8197,52 +9001,54 @@ class RedemptionApi {
      * ```
      */
     async getRedemptions(options) {
-        const params = [];
-        // Always include pagination params to ensure paginated response
-        params.push(`page=${options?.page || 1}`);
-        params.push(`limit=${options?.limit || 50}`);
+        // Always include pagination params (page/limit, plus sortBy/sortOrder) to ensure a paginated response
+        const params = buildPaginationParams(options);
         if (options?.active !== undefined)
-            params.push(`active=${options.active}`);
+            params.set('active', String(options.active));
         if (options?.search)
-            params.push(`search=${encodeURIComponent(options.search)}`);
+            params.set('search', options.search);
         // Support single tag or array of tags (multiple ?tags=a&tags=b)
         if (options?.tags) {
             const tagsArray = Array.isArray(options.tags) ? options.tags : [options.tags];
-            tagsArray.forEach(t => params.push(`tags=${encodeURIComponent(t)}`));
-        }
-        if (options?.startDate) {
-            const dateStr = options.startDate instanceof Date ? options.startDate.toISOString() : options.startDate;
-            params.push(`startDate=${encodeURIComponent(dateStr)}`);
-        }
-        if (options?.endDate) {
-            const dateStr = options.endDate instanceof Date ? options.endDate.toISOString() : options.endDate;
-            params.push(`endDate=${encodeURIComponent(dateStr)}`);
+            tagsArray.forEach(t => params.append('tags', t));
         }
-        if (options?.sortBy)
-            params.push(`sortBy=${options.sortBy}`);
-        if (options?.sortOrder)
-            params.push(`sortOrder=${options.sortOrder}`);
+        if (options?.ownerBusinessId)
+            params.set('ownerBusinessId', options.ownerBusinessId);
+        if (options?.approvalStatus)
+            params.set('approvalStatus', options.approvalStatus);
+        if (options?.status)
+            params.set('status', [options.status].flat().join(','));
+        if (options?.startDate)
+            params.set('startDate', options.startDate);
+        if (options?.endDate)
+            params.set('endDate', options.endDate);
         if (options?.include?.length)
-            params.push(`include=${options.include.join(',')}`);
-        const response = await this.apiClient.get(`${this.basePath}?${params.join('&')}`);
+            params.set('include', options.include.join(','));
+        const response = await this.apiClient.get(`${this.basePath}?${params.toString()}`);
         return normalizeToPaginated(response);
     }
     /**
      * PUBLIC: Get redemption types
      *
-     * Updated: /redemption/type → /redemption-types
+     * Updated: /redemption/type → /redemption-types
      * @param options Pagination options (page, limit, sortBy, sortOrder)
      * @returns Paginated response with redemption types
      */
     async getRedemptionTypes(options) {
         const params = buildPaginationParams(options);
+        setIncludeParam(params, options?.include);
         const response = await this.apiClient.get(`${this.typesPath}?${params.toString()}`);
         return normalizeToPaginated(response);
     }
+    /** PUBLIC: Get one redemption type; `translations` adds the raw per-locale map (admin editing). */
+    async getRedemptionTypeById(id, include) {
+        const params = include?.length ? `?include=${include.join(',')}` : '';
+        return this.apiClient.get(`${this.typesPath}/${id}${params}`);
+    }
     /**
      * PUBLIC: Get redemption by ID
      *
-     * Updated: /redemption/:id → /redemptions/:id
+     * Updated: /redemption/:id → /redemptions/:id
      *
      * @param id - Redemption UUID
      * @param include - Relations to include: 'redeemCount'
@@ -8261,7 +9067,7 @@ class RedemptionApi {
     /**
      * PUBLIC: Get available supply for redemption
      *
-     * Updated: /redemption/:id/available-supply → /redemptions/:id/supply
+     * Updated: /redemption/:id/available-supply → /redemptions/:id/supply
      */
     async getRedemptionAvailableSupply(id) {
         const result = await this.apiClient.get(`${this.basePath}/${id}/supply`);
@@ -8377,7 +9183,7 @@ class RedemptionApi {
     /**
      * ADMIN: Create redemption
      *
-     * Updated: /redemption/admin → /redemptions
+     * Updated: /redemption/admin → /redemptions
      */
     async createRedemption(redemption) {
         return this.apiClient.post(`${this.basePath}`, redemption);
@@ -8385,7 +9191,7 @@ class RedemptionApi {
     /**
      * ADMIN: Update redemption
      *
-     * Updated: /redemption/admin/:id → /redemptions/:id
+     * Updated: /redemption/admin/:id → /redemptions/:id
      */
     async updateRedemption(id, redemptionCreateRequest) {
         return this.apiClient.put(`${this.basePath}/${id}`, redemptionCreateRequest);
@@ -8393,7 +9199,7 @@ class RedemptionApi {
     /**
      * UNIFIED: Toggle redemption active status
      *
-     * Updated: /redemption/admin/:id/toggle-active → /redemptions/:id/status
+     * Updated: /redemption/admin/:id/toggle-active → /redemptions/:id/status
      * Following standard /status pattern used across domains
      */
     async toggleRedemptionActive(redemptionId) {
@@ -8402,7 +9208,7 @@ class RedemptionApi {
     /**
      * ADMIN: Delete redemption
      *
-     * Updated: /redemption/admin/:id → /redemptions/:id
+     * Updated: /redemption/admin/:id → /redemptions/:id
      */
     async deleteRedemption(id) {
         return this.apiClient.delete(`${this.basePath}/${id}`);
@@ -8410,7 +9216,7 @@ class RedemptionApi {
     /**
      * ADMIN: Create redemption type
      *
-     * Updated: /redemption/admin/type → /redemption-types
+     * Updated: /redemption/admin/type → /redemption-types
      */
     async createRedemptionType(redemptionType) {
         return this.apiClient.post(this.typesPath, redemptionType);
@@ -8437,7 +9243,7 @@ class RedemptionApi {
     /**
      * ADMIN: Create redemption token unit
      *
-     * Updated: /redemption/admin/:id/token-units → /redemption-tokens/:id/
+     * Updated: /redemption/admin/:id/token-units → /redemption-tokens/:id/
      */
     async createRedemptionTokenUnit(redemptionId, redemptionTokenUnit) {
         return this.apiClient.post(`${this.basePath}/${redemptionId}/tokens`, redemptionTokenUnit);
@@ -8445,7 +9251,7 @@ class RedemptionApi {
     /**
      * ADMIN: Update redemption token unit
      *
-     * Updated: /redemption/admin/:id/token-units/:tokenUnitId → /redemption-tokens/:id/:tokenUnitId
+     * Updated: /redemption/admin/:id/token-units/:tokenUnitId → /redemption-tokens/:id/:tokenUnitId
      */
     async updateRedemptionTokenUnit(redemptionId, tokenUnitId, redemptionTokenUnit) {
         return this.apiClient.put(`${this.basePath}/${redemptionId}/tokens/${tokenUnitId}`, redemptionTokenUnit);
@@ -8453,7 +9259,7 @@ class RedemptionApi {
     /**
      * ADMIN: Delete redemption token unit
      *
-     * Updated: /redemption/admin/:id/token-units/:tokenUnitId → /redemption-tokens/:id/:tokenUnitId
+     * Updated: /redemption/admin/:id/token-units/:tokenUnitId → /redemption-tokens/:id/:tokenUnitId
      */
     async deleteRedemptionTokenUnit(redemptionId, redemptionTokenUnitId) {
         return this.apiClient.delete(`${this.basePath}/${redemptionId}/tokens/${redemptionTokenUnitId}`);
@@ -8511,6 +9317,23 @@ class RedemptionApi {
         const url = `${this.basePath}/redeems/export/csv${queryString ? `?${queryString}` : ''}`;
         return this.apiClient.get(url, 'blob');
     }
+    // ==========================================
+    // ✅ APPROVAL WORKFLOW
+    // ==========================================
+    /**
+     * ADMIN: Approve a redemption
+     *
+     * Approves a redemption that is pending approval, changing its status to 'approved'.
+     *
+     * Endpoint: PATCH /admin/redemptions/:id/approve
+     * Auth: @TenantAdmin()
+     *
+     * @param redemptionId - ID of the redemption to approve
+     * @returns Updated redemption with approval metadata
+     */
+    async setRedemptionApproval(redemptionId, status, reason) {
+        return this.apiClient.patch(`/redemptions/${redemptionId}/approval`, { status, reason });
+    }
 }
 
 /**
@@ -8565,6 +9388,9 @@ class RedemptionService {
     async getRedemptionTypes(options) {
         return this.redemptionApi.getRedemptionTypes(options);
     }
+    async getRedemptionTypeById(id, include) {
+        return this.redemptionApi.getRedemptionTypeById(id, include);
+    }
     // ==========================================
     // AUTHENTICATED OPERATIONS
     // ==========================================
@@ -9581,11 +10407,12 @@ class PurchaseApi {
      * - ADMIN (Tenant Admin JWT): Returns filtered results based on active parameter
      *
      * @param active Filter by active status
-     * @param options Pagination options (page, limit, sortBy, sortOrder)
+     * @param options Pagination options (page, limit, sortBy, sortOrder) and `include: ['translations']` for admin editing
      * @returns Paginated response with purchase tokens
      */
     async getPurchaseTokens(active, options) {
         const params = buildPaginationParams(options);
+        setIncludeParam(params, options?.include);
         if (active !== undefined) {
             params.append('active', String(active));
         }
@@ -9690,7 +10517,7 @@ class PurchaseApi {
      */
     async getUserPurchaseHistory(options) {
         const params = buildPaginationParams(options);
-        const response = await this.apiClient.get(`${this.basePath}/me/history?${params.toString()}`);
+        const response = await this.apiClient.get(`${this.basePath}/me?${params.toString()}`);
         return normalizeToPaginated(response);
     }
 }
@@ -9777,10 +10604,10 @@ class TenantApi {
      * Requires: X-API-Key header + Authorization Bearer token (Admin JWT)
      * Returns: Full tenant information including allowedTokenIssuers and sensitive config
      */
-    async getRemoteTenant() {
-        const timestamp = Date.now().toString();
-        const url = `${this.basePath}/me?date=${timestamp}`;
-        return this.apiClient.get(url);
+    async getRemoteTenant(include) {
+        const params = new URLSearchParams({ date: Date.now().toString() });
+        setIncludeParam(params, include);
+        return this.apiClient.get(`${this.basePath}/me?${params.toString()}`);
     }
     /**
      * API KEY: Get current tenant public information
@@ -9789,10 +10616,10 @@ class TenantApi {
      * Requires: X-API-Key header (handled by PersApiClient)
      * Returns: Public tenant information (no sensitive config)
      */
-    async getRemoteTenantPublic() {
-        const timestamp = Date.now().toString();
-        const url = `${this.basePath}/me?date=${timestamp}`;
-        return this.apiClient.get(url);
+    async getRemoteTenantPublic(include) {
+        const params = new URLSearchParams({ date: Date.now().toString() });
+        setIncludeParam(params, include);
+        return this.apiClient.get(`${this.basePath}/me?${params.toString()}`);
     }
     /**
      * API KEY: Get remote login token
@@ -9817,9 +10644,11 @@ class TenantApi {
      *
      * @param tenantId - The tenant ID to retrieve public information for
      */
-    async getPublicTenantById(tenantId) {
-        const url = `${this.basePath}/${tenantId}`;
-        return this.apiClient.get(url);
+    async getPublicTenantById(tenantId, include) {
+        const params = new URLSearchParams();
+        setIncludeParam(params, include);
+        const query = params.toString();
+        return this.apiClient.get(`${this.basePath}/${tenantId}${query ? `?${query}` : ''}`);
     }
     // ==========================================
     // ADMIN OPERATIONS
@@ -9883,14 +10712,14 @@ class TenantService {
     /**
      * Get full tenant information (Admin JWT required)
      */
-    async getRemoteTenant() {
-        return this.tenantApi.getRemoteTenant();
+    async getRemoteTenant(include) {
+        return this.tenantApi.getRemoteTenant(include);
     }
     /**
      * PUBLIC: Get tenant public information (API key only)
      */
-    async getRemoteTenantPublic() {
-        return this.tenantApi.getRemoteTenantPublic();
+    async getRemoteTenantPublic(include) {
+        return this.tenantApi.getRemoteTenantPublic(include);
     }
     /**
      * PUBLIC: Get remote login token
@@ -9943,6 +10772,177 @@ class TenantService {
     }
 }
 
+/**
+ * IPFS Resolver - Gateway and URL resolution (chain-agnostic, no token or web3 types)
+ *
+ * @module @explorins/pers-sdk/ipfs
+ */
+const DEFAULT_IPFS_GATEWAY = 'gateway.pinata.cloud';
+class IpfsResolver {
+    constructor(config) {
+        this.config = config;
+        this.cache = globalCacheService.createNamespace('ipfs');
+    }
+    /** Tenant gateway domain; falls back to a public gateway so assets still load when unconfigured. */
+    getGatewayDomain() {
+        return this.cache.getOrSet('gateway', async () => {
+            const { ipfsGatewayDomain } = await this.config.getClientConfig();
+            if (!ipfsGatewayDomain) {
+                console.warn(`[PERS SDK] No ipfsGatewayDomain configured for the tenant, using ${DEFAULT_IPFS_GATEWAY}`);
+                return DEFAULT_IPFS_GATEWAY;
+            }
+            return ipfsGatewayDomain;
+        }, CacheTTL.GATEWAY);
+    }
+    /** `ipfs://` and `ar://` to HTTPS; HTTP(S) and unknown schemes pass through; empty input gives ''. */
+    async resolveUrl(url) {
+        if (!url)
+            return '';
+        if (url.startsWith('ipfs://')) {
+            return `https://${await this.getGatewayDomain()}/ipfs/${url.slice('ipfs://'.length)}`;
+        }
+        if (url.startsWith('ar://')) {
+            return `https://arweave.net/${url.slice('ar://'.length)}`;
+        }
+        return url;
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    /** Fetches JSON from any supported URI; throws on a non-OK response. */
+    async fetchJson(uri) {
+        const resolved = await this.resolveUrl(uri);
+        const response = await fetch(resolved);
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status} fetching ${resolved}`);
+        }
+        return response.json();
+    }
+}
+
+/**
+ * Token Metadata Resolver - The single place where ERC/OpenSea metadata JSON becomes SDK TokenMetadata
+ *
+ * Returns raw (language-agnostic) metadata and caches it: IPFS content is immutable.
+ * Callers apply the locale when handing the data out.
+ *
+ * @module @explorins/pers-sdk/token/metadata
+ */
+const STANDARD_KEYS = new Set([
+    'name', 'description', 'image', 'image_url', 'imageUrl',
+    'animation_url', 'animationUrl', 'external_url', 'externalUrl', 'attributes',
+]);
+const isResolvable = (value) => typeof value === 'string' && (value.startsWith('ipfs://') || value.startsWith('ar://'));
+const text = (...candidates) => {
+    const found = candidates.find(value => value !== undefined && value !== null && value !== '');
+    return found === undefined ? undefined : String(found);
+};
+class TokenMetadataResolver {
+    constructor(ipfs) {
+        this.ipfs = ipfs;
+        this.cache = globalCacheService.createNamespace('token-metadata');
+    }
+    /** Normalized metadata with HTTPS asset URLs, or null when it cannot be fetched. */
+    fetch(tokenUri) {
+        return this.cache.getOrSet(`processed:${tokenUri}`, async () => {
+            try {
+                return await this.load(tokenUri);
+            }
+            catch (error) {
+                console.warn(`[PERS SDK] Error fetching metadata from ${tokenUri}:`, error);
+                return null;
+            }
+        }, CacheTTL.METADATA);
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    async load(tokenUri) {
+        const raw = await this.ipfs.fetchJson(tokenUri);
+        // Resolve ipfs:// and ar:// references in any top-level string field
+        const resolved = { ...raw };
+        for (const [key, value] of Object.entries(resolved)) {
+            if (isResolvable(value))
+                resolved[key] = await this.ipfs.resolveUrl(value);
+        }
+        const customProperties = Object.fromEntries(Object.entries(resolved).filter(([key]) => !STANDARD_KEYS.has(key)));
+        return {
+            name: text(resolved.name) ?? '',
+            description: text(resolved.description) ?? '',
+            imageUrl: text(resolved.image, resolved.image_url, resolved.imageUrl) ?? '',
+            animationUrl: text(resolved.animation_url, resolved.animationUrl),
+            externalUrl: text(resolved.external_url, resolved.externalUrl),
+            attributes: Array.isArray(resolved.attributes) ? resolved.attributes : [],
+            ...customProperties,
+        };
+    }
+}
+function createIpfsSources(config) {
+    const resolver = new IpfsResolver(config);
+    return { resolver, metadata: new TokenMetadataResolver(resolver) };
+}
+
+/**
+ * Pure read-time localization of token metadata resolved from IPFS/HTTP (client-side path that
+ * bypasses the API). Caches keep the raw immutable JSON; callers apply the locale when handing data out.
+ *
+ * @module @explorins/pers-sdk/token/localization
+ */
+/**
+ * Replaces `name` and `description` with the translation for `locale` from the metadata's
+ * `translations` field (snapshotted at pin time). Falls back per field to the base text.
+ */
+function localizeTokenMetadata(metadata, locale) {
+    if (!locale || !metadata.translations)
+        return metadata;
+    return { ...metadata, ...localizeFields(metadata, locale, ['name', 'description']) };
+}
+/** Same instance when the locale is off or the metadata has no translations, so memoized consumers are not re-rendered. */
+function localizeTokenBalance(balance, locale) {
+    if (!locale || !balance.metadata)
+        return balance;
+    const metadata = localizeTokenMetadata(balance.metadata, locale);
+    return metadata === balance.metadata ? balance : { ...balance, metadata };
+}
+function localizeTokenCollection(collection, locale) {
+    if (!locale)
+        return collection;
+    const tokens = collection.tokens.map(token => localizeTokenBalance(token, locale));
+    return tokens.every((token, i) => token === collection.tokens[i]) ? collection : { ...collection, tokens };
+}
+
+/**
+ * IPFS Manager - Gateway, URL and token metadata resolution (chain-agnostic, no web3 dependencies)
+ *
+ * @example
+ * ```typescript
+ * const url = await sdk.ipfs.resolveUrl('ipfs://QmXxx...');
+ * const metadata = await sdk.ipfs.fetchMetadata('ipfs://QmXxx.../metadata.json');
+ * ```
+ */
+class IpfsManager {
+    constructor(config, getLocale = () => null) {
+        this.getLocale = getLocale;
+        this.sources = createIpfsSources(config);
+    }
+    /** Tenant IPFS gateway domain (cached; falls back to a public gateway when unconfigured) */
+    getGatewayDomain() {
+        return this.sources.resolver.getGatewayDomain();
+    }
+    /** Resolve `ipfs://` and `ar://` URLs to HTTPS; other URLs pass through */
+    resolveUrl(url) {
+        return this.sources.resolver.resolveUrl(url);
+    }
+    /**
+     * Fetch token metadata from a token URI (cached; IPFS content is immutable).
+     * name/description follow the SDK locale when the metadata carries translations.
+     */
+    async fetchMetadata(tokenUri) {
+        const metadata = await this.sources.metadata.fetch(tokenUri);
+        return metadata ? localizeTokenMetadata(metadata, this.getLocale()) : null;
+    }
+}
+
 /**
  * Tenant Manager - Clean, high-level interface for tenant operations
  *
@@ -9961,8 +10961,8 @@ class TenantManager {
      *
      * @returns Promise resolving to public tenant data
      */
-    async getTenantPublicInfo() {
-        return this.tenantService.getRemoteTenantPublic();
+    async getTenantPublicInfo(include) {
+        return this.tenantService.getRemoteTenantPublic(include);
     }
     /**
      * Get full tenant information including sensitive config (Admin JWT required)
@@ -9970,10 +10970,11 @@ class TenantManager {
      * Returns additional fields like allowedTokenIssuers that are only
      * available to authenticated tenant admins.
      *
+     * @param include - Pass `['translations']` to also receive the raw per-locale translations (admin editing)
      * @returns Promise resolving to full tenant data
      */
-    async getTenantInfo() {
-        return this.tenantService.getRemoteTenant();
+    async getTenantInfo(include) {
+        return this.tenantService.getRemoteTenant(include);
     }
     /**
      * Get tenant login token
@@ -10072,99 +11073,21 @@ class TenantManager {
     clearCache() {
         this.cache.clear();
     }
-    // ==========================================
-    // IPFS OPERATIONS (Lightweight, no Web3 deps)
-    // ==========================================
-    /**
-     * Get the IPFS gateway domain from tenant config (cached)
-     *
-     * @returns Promise resolving to IPFS gateway domain (e.g., 'gateway.pinata.cloud')
-     * @example
-     * ```typescript
-     * const gateway = await sdk.tenants.getIpfsGatewayDomain();
-     * // Returns 'gateway.pinata.cloud' or tenant-specific gateway
-     * ```
-     */
+    /** @internal Single IpfsManager per SDK; sdk.ipfs and the web3 adapter reuse it. */
+    get ipfs() {
+        return this._ipfs ?? (this._ipfs = new IpfsManager(this, () => this.apiClient.getLocale()));
+    }
+    /** @deprecated Use `sdk.ipfs.getGatewayDomain()` */
     async getIpfsGatewayDomain() {
-        return this.cache.getOrSet('ipfsGateway', async () => {
-            const config = await this.getClientConfig();
-            return config.ipfsGatewayDomain || 'gateway.pinata.cloud';
-        }, CacheTTL.LONG);
+        return this.ipfs.getGatewayDomain();
     }
-    /**
-     * Resolve an IPFS URL to an HTTP gateway URL
-     *
-     * @param url - The URL to resolve (ipfs://, ar://, or HTTP URL)
-     * @returns Promise resolving to HTTP gateway URL
-     *
-     * @example
-     * ```typescript
-     * const httpUrl = await sdk.tenants.resolveIpfsUrl('ipfs://QmXxx...');
-     * // Returns 'https://gateway.pinata.cloud/ipfs/QmXxx...'
-     * ```
-     */
+    /** @deprecated Use `sdk.ipfs.resolveUrl()` */
     async resolveIpfsUrl(url) {
-        if (!url)
-            return '';
-        // Already an HTTP URL
-        if (url.startsWith('http://') || url.startsWith('https://')) {
-            return url;
-        }
-        const gateway = await this.getIpfsGatewayDomain();
-        // Handle ipfs:// protocol
-        if (url.startsWith('ipfs://')) {
-            const cid = url.replace('ipfs://', '');
-            return `https://${gateway}/ipfs/${cid}`;
-        }
-        // Handle ar:// (Arweave) protocol
-        if (url.startsWith('ar://')) {
-            const txId = url.replace('ar://', '');
-            return `https://arweave.net/${txId}`;
-        }
-        return url;
+        return this.ipfs.resolveUrl(url);
     }
-    /**
-     * Fetch and process token metadata from IPFS/HTTP URI
-     *
-     * @param tokenUri - The token URI (ipfs://, ar://, or HTTP)
-     * @returns Promise resolving to processed metadata or null on error
-     *
-     * @example
-     * ```typescript
-     * const metadata = await sdk.tenants.fetchAndProcessMetadata('ipfs://QmXxx.../metadata.json');
-     * if (metadata) {
-     *   console.log(metadata.name, metadata.imageUrl);
-     * }
-     * ```
-     */
+    /** @deprecated Use `sdk.ipfs.fetchMetadata()` */
     async fetchAndProcessMetadata(tokenUri) {
-        try {
-            const resolvedUri = await this.resolveIpfsUrl(tokenUri);
-            const response = await fetch(resolvedUri);
-            if (!response.ok) {
-                console.warn(`Failed to fetch metadata from ${resolvedUri}: ${response.status}`);
-                return null;
-            }
-            const rawMetadata = await response.json();
-            // Normalize the metadata - resolve image URLs
-            const imageUrl = rawMetadata.image || rawMetadata.image_url || rawMetadata.imageUrl || '';
-            const resolvedImageUrl = await this.resolveIpfsUrl(imageUrl);
-            const animationUrl = rawMetadata.animation_url || rawMetadata.animationUrl || '';
-            const resolvedAnimationUrl = animationUrl ? await this.resolveIpfsUrl(animationUrl) : undefined;
-            return {
-                name: rawMetadata.name || 'Untitled',
-                description: rawMetadata.description || '',
-                imageUrl: resolvedImageUrl,
-                animationUrl: resolvedAnimationUrl,
-                externalUrl: rawMetadata.external_url || rawMetadata.externalUrl,
-                attributes: rawMetadata.attributes,
-                ...rawMetadata // Include any additional properties
-            };
-        }
-        catch (error) {
-            console.warn(`Error fetching metadata from ${tokenUri}:`, error);
-            return null;
-        }
+        return this.ipfs.fetchMetadata(tokenUri);
     }
 }
 
@@ -10639,6 +11562,7 @@ class TriggerSourceApi {
      */
     async getTriggerSources(options) {
         const params = buildPaginationParams(options);
+        setIncludeParam(params, options?.include);
         if (options?.type)
             params.set('type', options.type);
         if (options?.businessId)
@@ -10669,8 +11593,11 @@ class TriggerSourceApi {
      * @param triggerSourceId - UUID of the trigger source
      * @returns Trigger source details
      */
-    async getTriggerSourceById(triggerSourceId) {
-        return this.apiClient.get(`/trigger-sources/${triggerSourceId}`);
+    async getTriggerSourceById(triggerSourceId, include) {
+        const params = new URLSearchParams();
+        setIncludeParam(params, include);
+        const query = params.toString();
+        return this.apiClient.get(`/trigger-sources/${triggerSourceId}${query ? `?${query}` : ''}`);
     }
     /**
      * ADMIN: Create a new trigger source
@@ -10733,8 +11660,8 @@ class TriggerSourceService {
     /**
      * Get trigger source by ID
      */
-    async getTriggerSourceById(triggerSourceId) {
-        return this.triggerSourceApi.getTriggerSourceById(triggerSourceId);
+    async getTriggerSourceById(triggerSourceId, include) {
+        return this.triggerSourceApi.getTriggerSourceById(triggerSourceId, include);
     }
     /**
      * ADMIN: Create a new trigger source
@@ -11212,9 +12139,14 @@ class AuthService {
         if (this.activeRefreshPromise) {
             return;
         }
-        // If auth failure is already in progress, wait for it
+        // If auth failure is already in progress, return immediately.
+        // DO NOT await activeAuthFailurePromise here - it causes a deadlock when
+        // handleAuthFailure() is called from within the recovery attempt itself.
+        // Example: recovery calls loginUser() → POST /auth/token → 401 → handleAuthFailure()
+        // Awaiting the outer promise from inside it creates a circular wait that never resolves.
+        // The outer failure handler will complete and emit AUTH_FAILED regardless.
         if (this.activeAuthFailurePromise) {
-            return await this.activeAuthFailurePromise;
+            return;
         }
         // Create the failure promise to deduplicate concurrent calls
         this.activeAuthFailurePromise = this.performAuthFailureWithRecovery();
@@ -11399,6 +12331,9 @@ class TokenRefreshManager {
         // Retry configuration for transient failures
         this.MAX_RETRY_ATTEMPTS = 3;
         this.RETRY_DELAY_MS = 1000;
+        // After a transient refresh failure, skip further attempts for a while so every request doesn't wait through the retries again
+        this.lastRetryableFailureTime = 0;
+        this.RETRYABLE_FAILURE_COOLDOWN_MS = 15000;
         // Active refresh promise for deduplication
         this.activeRefreshPromise = null;
     }
@@ -11412,33 +12347,37 @@ class TokenRefreshManager {
         if (now - this.lastValidationTime < this.validationCacheDurationMs) {
             return;
         }
+        if (now - this.lastRetryableFailureTime < this.RETRYABLE_FAILURE_COOLDOWN_MS) {
+            return;
+        }
         try {
             const token = await this.authProvider.getToken();
             if (!token) {
-                return;
-            }
-            // Calculate dynamic refresh margin based on token lifetime
-            const marginSeconds = this.calculateRefreshMargin(token);
-            if (isTokenExpired(token, marginSeconds)) {
-                const result = await this.attemptRefreshWithRetry();
-                if (!result.success) {
-                    if (result.retryable) {
-                        // Transient error - don't logout, let next request retry
-                        console.warn('[TokenRefreshManager] Refresh failed with retryable error, will retry on next request');
-                        return;
-                    }
-                    // Definitive auth failure - logout required
-                    await this.authService.handleAuthFailure();
-                }
-                else {
-                    // Refresh successful
-                    this.lastValidationTime = now;
+                // No access token but a stored refresh token: refresh now instead of sending an anonymous request
+                const refreshToken = await this.authProvider.getRefreshToken?.();
+                if (!refreshToken) {
+                    return;
                 }
             }
-            else {
+            else if (!isTokenExpired(token, this.calculateRefreshMargin(token))) {
                 // Token is valid
                 this.lastValidationTime = now;
+                return;
+            }
+            const result = await this.attemptRefreshWithRetry();
+            if (result.success) {
+                this.lastValidationTime = now;
+                this.lastRetryableFailureTime = 0;
+                return;
+            }
+            if (result.retryable) {
+                // Transient error - don't logout, let a later request retry after the cooldown
+                console.warn('[TokenRefreshManager] Refresh failed with retryable error, will retry after cooldown');
+                this.lastRetryableFailureTime = Date.now();
+                return;
             }
+            // Definitive auth failure - logout required
+            await this.authService.handleAuthFailure();
         }
         catch (error) {
             // Unexpected error - log but don't logout (conservative approach)
@@ -11508,13 +12447,24 @@ class TokenRefreshManager {
         if (this.activeRefreshPromise) {
             return this.activeRefreshPromise;
         }
+        if (Date.now() - this.lastRetryableFailureTime < this.RETRYABLE_FAILURE_COOLDOWN_MS) {
+            return { success: false, retryable: true };
+        }
         this.activeRefreshPromise = (async () => {
             const result = await this.attemptRefreshWithRetry();
-            if (result.success)
+            if (result.success) {
+                this.lastRetryableFailureTime = 0;
                 return result;
+            }
             // Internal failed - try provider token recovery
             const recovered = await this.authService.attemptProviderTokenRecovery();
-            return recovered ? { success: true, retryable: false } : result;
+            if (recovered) {
+                this.lastRetryableFailureTime = 0;
+                return { success: true, retryable: false };
+            }
+            if (result.retryable)
+                this.lastRetryableFailureTime = Date.now();
+            return result;
         })();
         try {
             return await this.activeRefreshPromise;
@@ -11602,7 +12552,9 @@ class AuthTokenManager {
         const val = await this.storage.get(AUTH_STORAGE_KEYS.ACCESS_TOKEN);
         // Ensure we return string for tokens
         const token = typeof val === 'string' ? val : null;
-        this.cache.accessToken = token;
+        // Never cache a miss: a transient storage failure (e.g. locked iOS Keychain) would otherwise log the user out for the whole session
+        if (token)
+            this.cache.accessToken = token;
         return token;
     }
     async setAccessToken(token) {
@@ -11616,7 +12568,8 @@ class AuthTokenManager {
         }
         const val = await this.storage.get(AUTH_STORAGE_KEYS.REFRESH_TOKEN);
         const token = typeof val === 'string' ? val : null;
-        this.cache.refreshToken = token;
+        if (token)
+            this.cache.refreshToken = token;
         return token;
     }
     async setRefreshToken(token) {
@@ -11630,7 +12583,8 @@ class AuthTokenManager {
         }
         const val = await this.storage.get(AUTH_STORAGE_KEYS.PROVIDER_TOKEN);
         const token = typeof val === 'string' ? val : null;
-        this.cache.providerToken = token;
+        if (token)
+            this.cache.providerToken = token;
         return token;
     }
     async setProviderToken(token) {
@@ -11644,7 +12598,8 @@ class AuthTokenManager {
         }
         const authType = await this.storage.get(AUTH_STORAGE_KEYS.AUTH_TYPE);
         const type = typeof authType === 'string' ? authType : null;
-        this.cache.authType = type;
+        if (type)
+            this.cache.authType = type;
         return type;
     }
     async setAuthType(authType) {
@@ -12327,7 +13282,7 @@ class DefaultAuthProvider {
 /** SDK package name */
 const SDK_NAME = "@explorins/pers-sdk";
 /** SDK version - injected from package.json at build time */
-const SDK_VERSION = "2.3.12";
+const SDK_VERSION = "2.3.38";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
@@ -12460,6 +13415,56 @@ class TrackingManager {
     }
 }
 
+/**
+ * Locale Manager - Content language for localized API responses
+ *
+ * Opt-in: no locale means no `x-locale` header and base-language strings.
+ *
+ * @module @explorins/pers-sdk/core/locale
+ */
+/** Device locale via `Intl`, or null where it is unavailable. */
+function detectDeviceLocale() {
+    try {
+        return normalizeLocale(Intl.DateTimeFormat().resolvedOptions().locale);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Holds the configured locale and resolves it to a normalized tag.
+ */
+class LocaleManager {
+    constructor(locale) {
+        this.listeners = new Set();
+        this.setting = locale;
+    }
+    /** Set the locale (`'auto'`, a BCP 47 tag, or `null` to disable). Listeners run when the effective locale changes. */
+    setLocale(locale) {
+        const before = this.getLocale();
+        this.setting = locale;
+        const after = this.getLocale();
+        if (after !== before)
+            this.listeners.forEach(listener => listener(after));
+    }
+    /** Subscribe to effective-locale changes (e.g. to drop locale-dependent caches). Returns an unsubscribe function. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Normalized locale in effect, or null when disabled or invalid. */
+    getLocale() {
+        if (!this.setting)
+            return null;
+        return this.setting === 'auto' ? detectDeviceLocale() : normalizeLocale(this.setting);
+    }
+    /** @internal - Used by PersApiClient */
+    buildHeaders() {
+        const locale = this.getLocale();
+        return locale ? { [LOCALE_HEADER]: locale } : {};
+    }
+}
+
 // packages/pers-sdk/src/core/pers-api-client.ts
 /**
  * PERS API Client - Platform-agnostic HTTP client with authentication
@@ -12513,6 +13518,7 @@ class PersApiClient {
             dataSource: this.mergedConfig.dataSource,
             platform: this.mergedConfig.platform,
         });
+        this.localeManager = new LocaleManager(this.mergedConfig.locale);
         if (this.mergedConfig.authProvider) {
             this.initializationPromise = this.initialize();
         }
@@ -12570,7 +13576,8 @@ class PersApiClient {
             await this.ensureInitialized();
         }
         const { retryCount = 0, responseType = 'json', bypassAuth = false } = options || {};
-        const url = `${this.apiRoot}${endpoint}`;
+        const cacheBust = options?.cacheBust ? `${endpoint.includes('?') ? '&' : '?'}_=${Date.now()}` : '';
+        const url = `${this.apiRoot}${endpoint}${cacheBust}`;
         // TOKEN VALIDATION: Ensure token is valid before request
         // This blocks the request until token validation completes - prevents 401s from expired tokens
         if (!bypassAuth && this.mergedConfig.authProvider && retryCount === 0) {
@@ -12599,6 +13606,9 @@ class PersApiClient {
                 case 'PUT':
                     result = await this.httpClient.put(url, body, requestOptions);
                     break;
+                case 'PATCH':
+                    result = await this.httpClient.patch(url, body, requestOptions);
+                    break;
                 case 'DELETE':
                     result = await this.httpClient.delete(url, requestOptions);
                     break;
@@ -12610,11 +13620,15 @@ class PersApiClient {
         catch (error) {
             const status = ErrorUtils.getStatus(error);
             const errorMessage = ErrorUtils.getMessage(error);
+            // A bare 304 means the platform HTTP cache did not merge it into a 200: refetch once under a unique URL
+            if (status === 304 && method === 'GET' && !options?.cacheBust) {
+                return await this.request(method, endpoint, body, { ...options, cacheBust: true });
+            }
             // Handle 401 Unauthorized errors
             if (status === 401) {
                 const backendError = ErrorUtils.extractBackendErrorDetails(error);
                 // ===========================================
-                // FATAL AUTH ERRORS → Immediate logout
+                // FATAL AUTH ERRORS → Immediate logout
                 // ===========================================
                 // Fatal codes: REFRESH_TOKEN_EXPIRED, TOKEN_REVOKED, INVALID_REFRESH_TOKEN, etc.
                 if (this.authService.isFatalAuthError(backendError.code)) {
@@ -12624,7 +13638,7 @@ class PersApiClient {
                     throw new AuthenticationError(errorMessage, endpoint, method, backendError);
                 }
                 // ===========================================
-                // REFRESH REQUEST FAILED → Logout (prevents infinite loop)
+                // REFRESH REQUEST FAILED → Logout (prevents infinite loop)
                 // ===========================================
                 if (options?.isRefreshRequest) {
                     console.warn('[PersApiClient] Refresh request itself failed with 401');
@@ -12633,12 +13647,12 @@ class PersApiClient {
                     throw new AuthenticationError(errorMessage, endpoint, method, backendError);
                 }
                 // ===========================================
-                // RETRYABLE 401 (TOKEN_EXPIRED) → Try refresh, then retry
+                // RETRYABLE 401 (TOKEN_EXPIRED) → Try refresh, then retry
                 // ===========================================
                 if (retryCount === 0 && this.mergedConfig.authProvider) {
                     const refreshResult = await this.refreshManager.attemptInternalRefresh();
                     if (refreshResult.success) {
-                        // Refresh succeeded → retry request with new token
+                        // Refresh succeeded → retry request with new token
                         this._events?.emitSuccess({
                             type: 'token_refreshed',
                             domain: 'authentication',
@@ -12648,19 +13662,19 @@ class PersApiClient {
                     }
                     // Refresh failed - check if it's a definitive failure
                     if (!refreshResult.retryable) {
-                        // Non-retryable failure (e.g., refresh token expired) → logout
+                        // Non-retryable failure (e.g., refresh token expired) → logout
                         console.warn('[PersApiClient] Refresh failed with non-retryable error, logging out');
                         await this.authService.handleAuthFailure();
                     }
                     else {
-                        // Retryable failure (network error, etc.) → DON'T logout, let app retry later
+                        // Retryable failure (network error, etc.) → DON'T logout, let app retry later
                         console.warn('[PersApiClient] Refresh failed with retryable error, NOT logging out');
                     }
                     this.emitErrorEvent(backendError, errorMessage, endpoint, method, status, error);
                     throw new AuthenticationError(errorMessage, endpoint, method, backendError);
                 }
                 // ===========================================
-                // RETRY FAILED (retryCount > 0) → Something wrong, but DON'T logout
+                // RETRY FAILED (retryCount > 0) → Something wrong, but DON'T logout
                 // ===========================================
                 // We already refreshed successfully, but retry still got 401
                 // This is unexpected - don't logout, let app investigate
@@ -12737,6 +13751,9 @@ class PersApiClient {
     async put(endpoint, body) {
         return this.request('PUT', endpoint, body);
     }
+    async patch(endpoint, body) {
+        return this.request('PATCH', endpoint, body);
+    }
     /**
      * Generic DELETE request
      */
@@ -12799,6 +13816,8 @@ class PersApiClient {
         }
         // Add tracking headers (data source + platform)
         Object.assign(headers, this.tracking.buildHeaders());
+        // Opt-in content locale
+        Object.assign(headers, this.localeManager.buildHeaders());
         return headers;
     }
     // ==========================================
@@ -12822,6 +13841,15 @@ class PersApiClient {
     getOriginalConfig() {
         return this.config;
     }
+    /**
+     * Get the resolved API root URL (e.g. `https://api.pers.ninja/v2`)
+     *
+     * Useful for building fully-qualified URLs outside of `apiClient.get/post/...`,
+     * such as public redirect/QR target links.
+     */
+    getApiRoot() {
+        return this.apiRoot;
+    }
     // ==========================================
     // DATA SOURCE TRACKING
     // ==========================================
@@ -12849,6 +13877,21 @@ class PersApiClient {
     validateTracking() {
         return this.tracking.validate();
     }
+    // ==========================================
+    // CONTENT LOCALE
+    // ==========================================
+    /** Set the content locale (`'auto'`, a BCP 47 tag, or `null` to disable) */
+    setLocale(locale) {
+        this.localeManager.setLocale(locale);
+    }
+    /** Normalized content locale in effect, or null when disabled */
+    getLocale() {
+        return this.localeManager.getLocale();
+    }
+    /** Subscribe to effective-locale changes; returns an unsubscribe function */
+    onLocaleChange(listener) {
+        return this.localeManager.onChange(listener);
+    }
 }
 
 /**
@@ -13661,6 +14704,9 @@ class AuthManager {
  *   key: 'city',
  *   value: 'New York'
  * });
+ *
+ * // Get a single user's public profile by ID (no auth required)
+ * const oneProfile = await sdk.users.getPublicProfile('user-123');
  * ```
  *
  * @example Administrative Operations
@@ -13715,7 +14761,14 @@ class UserManager {
      * ```
      */
     async getCurrentUser(options) {
-        return this.userService.getRemoteUser(options);
+        const user = await this.userService.getRemoteUser(options);
+        this.events?.emitSuccess({
+            domain: 'user',
+            type: 'user_loaded',
+            userMessage: 'User loaded',
+            details: { user }
+        });
+        return user;
     }
     /**
      * Update current user profile
@@ -13748,7 +14801,7 @@ class UserManager {
         const result = await this.userService.updateRemoteUser(userData);
         this.events?.emitSuccess({
             domain: 'user',
-            type: 'profile_updated',
+            type: 'user_updated',
             userMessage: 'Profile updated successfully',
             details: { userId: result.id }
         });
@@ -13830,6 +14883,26 @@ class UserManager {
     async getAllUsersPublic(filter, options) {
         return this.userService.getAllUsersPublicProfiles(filter || null, options);
     }
+    /**
+     * Get a single user's public profile by ID
+     *
+     * Retrieves the publicly viewable profile for one user, without requiring
+     * authentication. Useful for public profile pages/widgets where the viewer
+     * may or may not be logged in as that user.
+     *
+     * @param id - The user's unique ID
+     * @returns Promise resolving to the user's public profile
+     * @throws {PersApiError} When no user exists with that ID
+     *
+     * @example Public Profile Page
+     * ```typescript
+     * const profile = await sdk.users.getPublicProfile(routeId);
+     * console.log(profile.publicProfile);
+     * ```
+     */
+    async getPublicProfile(id) {
+        return this.userService.getPublicProfileById(id);
+    }
     /**
      * Admin: Get all users
      *
@@ -14138,6 +15211,12 @@ class UserStatusManager {
     async getUserStatusTypes(options) {
         return this.userStatusSDK.getRemoteUserStatusTypes(options);
     }
+    /**
+     * Get one user status type by ID; `include: ['translations']` adds the raw per-locale map for editing
+     */
+    async getUserStatusTypeById(id, include) {
+        return this.userStatusSDK.getRemoteUserStatusTypeById(id, include);
+    }
     /**
      * Get earned user status for authenticated user
      *
@@ -14434,6 +15513,19 @@ class TokenManager {
     async getTokenMetadata(options) {
         return this.tokenService.getTokenMetadata(options);
     }
+    /**
+     * Get one reward or stamp metadata by ID (admin/business)
+     *
+     * @param include - Same relations as the list; `translations` adds the raw per-locale map for editing
+     *
+     * @example
+     * ```typescript
+     * const metadata = await sdk.tokens.getTokenMetadataById(id, ['translations']);
+     * ```
+     */
+    async getTokenMetadataById(metadataId, include) {
+        return this.tokenService.getTokenMetadataById(metadataId, include);
+    }
     /**
      * Get rewards (ERC1155 token metadata) with filtering, pagination, and include relations
      *
@@ -14634,7 +15726,7 @@ class TokenManager {
         return this.tokenService;
     }
     // ==========================================
-    // 📊 CSV EXPORT
+    // 📊 CSV EXPORT
     // ==========================================
     /**
      * Admin: Export token metadata to CSV
@@ -14668,6 +15760,29 @@ class TokenManager {
     async exportMetadataCSV(options) {
         return this.tokenService.exportMetadataCSV(options);
     }
+    // ==========================================
+    // ✅ APPROVAL WORKFLOW
+    // ==========================================
+    /**
+     * Admin: Approve token metadata
+     *
+     * Approves token metadata that is pending approval. This operation is only available
+     * when the tenant has token metadata approval enabled in their approval settings.
+     *
+     * @param tokenMetadataId - ID of the token metadata to approve
+     * @returns Promise resolving to updated token metadata with approval metadata
+     * @throws {PersApiError} When not authenticated as tenant admin or token metadata not found
+     *
+     * @example
+     * `	ypescript
+     * const approved = await sdk.tokens.approveTokenMetadata('metadata-123');
+     * console.log('Token metadata approved at:', approved.approval?.approvedAt);
+     * `
+     */
+    async setTokenMetadataApproval(tokenMetadataId, status, reason) {
+        const tokenApi = new TokenApi(this.apiClient);
+        return tokenApi.setTokenMetadataApproval(tokenMetadataId, status, reason);
+    }
 }
 
 /**
@@ -14763,6 +15878,20 @@ class BusinessManager {
     async getActiveBusinesses(options) {
         return this.businessService.getActiveBusinesses(options);
     }
+    /**
+     * Get the distinct list of cities that have at least one business, for populating
+     * city filter options before calling `getBusinesses({ city })`.
+     *
+     * @example
+     * ```typescript
+     * const cities = await sdk.business.getBusinessCities();
+     * // Render as filter options, then:
+     * const dohaBusinesses = await sdk.business.getBusinesses({ city: cities[0] });
+     * ```
+     */
+    async getBusinessCities(options) {
+        return this.businessService.getBusinessCities(options);
+    }
     /**
      * Get business by ID
      *
@@ -14790,8 +15919,8 @@ class BusinessManager {
      * }
      * ```
      */
-    async getBusinessById(businessId) {
-        return this.businessService.getBusinessById(businessId);
+    async getBusinessById(businessId, include) {
+        return this.businessService.getBusinessById(businessId, include);
     }
     /**
      * Get business by account address
@@ -14845,7 +15974,13 @@ class BusinessManager {
      * ```
      */
     async getBusinessTypes(options) {
-        return this.businessService.getBusinessTypes();
+        return this.businessService.getBusinessTypes(options);
+    }
+    /**
+     * Get one business type by ID; `include: ['translations']` adds the raw per-locale map for editing
+     */
+    async getBusinessTypeById(id, include) {
+        return this.businessService.getBusinessTypeById(id, include);
     }
     /**
      * Admin: Create a new business type
@@ -15004,8 +16139,8 @@ class BusinessManager {
      * });
      * ```
      */
-    async createBusiness(displayName) {
-        const result = await this.businessService.createBusinessByDisplayName(displayName);
+    async createBusiness(dto) {
+        const result = await this.businessService.createBusiness(dto);
         this.events?.emitSuccess({
             domain: 'business',
             type: 'business_created',
@@ -15310,7 +16445,7 @@ class BusinessManager {
         return this.membershipService;
     }
     // ==========================================
-    // 📊 CSV EXPORT
+    // 📊 CSV EXPORT
     // ==========================================
     /**
      * Admin: Export businesses to CSV
@@ -15341,6 +16476,33 @@ class BusinessManager {
      * a.click();
      * ```
      */
+    // ==========================================
+    // ✅ APPROVAL WORKFLOW
+    // ==========================================
+    /**
+     * Admin: Approve a business
+     *
+     * Approves a business that is pending approval. This operation is only available
+     * when the tenant has business approval enabled in their approval settings.
+     *
+     * @param businessId - ID of the business to approve
+     * @returns Promise resolving to updated business with approval metadata
+     * @throws {PersApiError} When not authenticated as tenant admin or business not found
+     *
+     * @example
+     * `	ypescript
+     * // Approve pending business
+     * const approvedBusiness = await sdk.businesses.approveBusiness('business-123');
+     *
+     * console.log('Business approved!');
+     * console.log('Approved by:', approvedBusiness.approval?.approvedBy);
+     * console.log('Approved at:', approvedBusiness.approval?.approvedAt);
+     * console.log('Status:', approvedBusiness.approval?.status); // 'approved'
+     * `
+     */
+    async setBusinessApproval(businessId, status, reason) {
+        return this.businessApi.setBusinessApproval(businessId, status, reason);
+    }
     async exportCSV(options) {
         return this.businessApi.exportCSV(options);
     }
@@ -15557,7 +16719,7 @@ class CampaignManager {
      *   if (claim.rewards?.length) {
      *     console.log(`   Rewards:`);
      *     claim.rewards.forEach(reward => {
-     *       console.log(`      • ${reward.amount} ${reward.token.symbol}`);
+     *       console.log(`      • ${reward.amount} ${reward.token.symbol}`);
      *     });
      *   }
      * });
@@ -16368,6 +17530,29 @@ class CampaignManager {
     getCampaignService() {
         return this.campaignService;
     }
+    // ==========================================
+    // ✅ APPROVAL WORKFLOW
+    // ==========================================
+    /**
+     * Admin: Approve a campaign
+     *
+     * Approves a campaign that is pending approval. This operation is only available
+     * when the tenant has campaign approval enabled in their approval settings.
+     *
+     * @param campaignId - ID of the campaign to approve
+     * @returns Promise resolving to updated campaign with approval metadata
+     * @throws {PersApiError} When not authenticated as tenant admin or campaign not found
+     *
+     * @example
+     * `	ypescript
+     * const approvedCampaign = await sdk.campaigns.approveCampaign('campaign-123');
+     * console.log('Campaign approved at:', approvedCampaign.approval?.approvedAt);
+     * `
+     */
+    async setCampaignApproval(campaignId, status, reason) {
+        const campaignApi = new CampaignApi(this.apiClient);
+        return campaignApi.setCampaignApproval(campaignId, status, reason);
+    }
 }
 
 /**
@@ -16633,6 +17818,12 @@ class RedemptionManager {
     async getRedemptionTypes(options) {
         return this.redemptionService.getRedemptionTypes(options);
     }
+    /**
+     * Get one redemption type by ID; `include: ['translations']` adds the raw per-locale map for editing
+     */
+    async getRedemptionTypeById(id, include) {
+        return this.redemptionService.getRedemptionTypeById(id, include);
+    }
     /**
      * Redeem a redemption offer
      *
@@ -16645,8 +17836,9 @@ class RedemptionManager {
      * issues ERC721 tokens. Context can include validity dates, AI prompt placeholders,
      * and custom metadata.
      *
-     * @param redemptionId - ID of the redemption offer to redeem
-     * @param context - Optional dynamic context for NFT personalization (validity dates, AI prompts)
+     * @param request - Redemption ID string, or a full `RedemptionRedeemRequestDTO` object
+     *   (supports `redemptionId`, `businessId`, and `context` fields)
+     * @param context - Optional dynamic context when passing a plain `redemptionId` string
      * @returns Promise resolving to redemption result with confirmation details
      * @throws {PersApiError} When redemption is not available or user lacks required tokens
      *
@@ -16741,16 +17933,16 @@ class RedemptionManager {
      * }
      * ```
      */
-    async redeem(redemptionId, context) {
-        const request = context
-            ? { redemptionId, context }
-            : { redemptionId };
-        const result = await this.redemptionService.redeemRedemption(request);
+    async redeem(request, context) {
+        const requestBody = typeof request === 'string'
+            ? { redemptionId: request, ...(context ? { context } : {}) }
+            : request;
+        const result = await this.redemptionService.redeemRedemption(requestBody);
         this.events?.emitSuccess({
             domain: 'redemption',
             type: 'redeem_success',
             userMessage: 'Reward redeemed successfully',
-            details: { redemptionId, hasContext: !!context }
+            details: { redemptionId: requestBody.redemptionId, hasContext: !!(requestBody.context ?? context) }
         });
         return result;
     }
@@ -17231,6 +18423,29 @@ class RedemptionManager {
     getRedemptionService() {
         return this.redemptionService;
     }
+    // ==========================================
+    // ✅ APPROVAL WORKFLOW
+    // ==========================================
+    /**
+     * Admin: Approve a redemption
+     *
+     * Approves a redemption that is pending approval. This operation is only available
+     * when the tenant has redemption approval enabled in their approval settings.
+     *
+     * @param redemptionId - ID of the redemption to approve
+     * @returns Promise resolving to updated redemption with approval metadata
+     * @throws {PersApiError} When not authenticated as tenant admin or redemption not found
+     *
+     * @example
+     * `	ypescript
+     * const approved = await sdk.redemptions.approveRedemption('redemption-123');
+     * console.log('Redemption approved at:', approved.approval?.approvedAt);
+     * `
+     */
+    async setRedemptionApproval(redemptionId, status, reason) {
+        const redemptionApi = new RedemptionApi(this.apiClient);
+        return redemptionApi.setRedemptionApproval(redemptionId, status, reason);
+    }
 }
 
 /**
@@ -18826,7 +20041,7 @@ class ApiKeyManager {
      */
     async listApiKeys(type, includeRevoked = false, options) {
         try {
-            return await this.apiKeyApi.getTenantApiKeys(type, includeRevoked);
+            return await this.apiKeyApi.getTenantApiKeys(type, includeRevoked, options);
         }
         catch (error) {
             console.error('[ApiKeyManager] Failed to list API keys:', error);
@@ -19585,8 +20800,8 @@ class TriggerSourceManager {
      * }
      * ```
      */
-    async getById(triggerSourceId) {
-        return this.triggerSourceService.getTriggerSourceById(triggerSourceId);
+    async getById(triggerSourceId, include) {
+        return this.triggerSourceService.getTriggerSourceById(triggerSourceId, include);
     }
     /**
      * Admin: Create a new trigger source
@@ -19707,6 +20922,207 @@ class TriggerSourceManager {
     }
 }
 
+/**
+ * Platform-Agnostic Redirect API Client
+ *
+ * Handles QR code / short-link redirect operations:
+ * - CRUD for tenant/business-owned redirects
+ * - Per-redirect scan analytics
+ *
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ */
+class RedirectApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    /**
+     * ADMIN: Create a new redirect
+     *
+     * @example
+     * ```typescript
+     * const redirect = await redirectApi.createRedirect({
+     *   targetUrl: 'https://app.pers.ninja/campaigns/abc',
+     *   label: 'Summer Campaign QR'
+     * });
+     * ```
+     */
+    async createRedirect(redirect) {
+        return this.apiClient.post('/redirects', redirect);
+    }
+    /**
+     * ADMIN: List all redirects for the current tenant
+     */
+    async getRedirects() {
+        return this.apiClient.get('/redirects');
+    }
+    /**
+     * ADMIN: Get a redirect by ID
+     */
+    async getRedirectById(redirectId) {
+        return this.apiClient.get(`/redirects/${redirectId}`);
+    }
+    /**
+     * ADMIN: Update a redirect's label or target URL
+     */
+    async updateRedirect(redirectId, redirect) {
+        return this.apiClient.patch(`/redirects/${redirectId}`, redirect);
+    }
+    /**
+     * ADMIN: Soft-delete a redirect
+     */
+    async deleteRedirect(redirectId) {
+        await this.apiClient.delete(`/redirects/${redirectId}`);
+    }
+    /**
+     * TENANT ONLY: Get scan analytics for a redirect
+     *
+     * @example
+     * ```typescript
+     * const stats = await redirectApi.getRedirectAnalytics(redirectId, { from: '2025-01-01' });
+     * ```
+     */
+    async getRedirectAnalytics(redirectId, options) {
+        const params = new URLSearchParams();
+        if (options?.from)
+            params.set('from', this.toDateParam(options.from));
+        if (options?.to)
+            params.set('to', this.toDateParam(options.to));
+        const query = params.toString();
+        return this.apiClient.get(`/redirects/${redirectId}/analytics${query ? `?${query}` : ''}`);
+    }
+    toDateParam(value) {
+        return value instanceof Date ? value.toISOString() : value;
+    }
+}
+
+/**
+ * Platform-Agnostic Redirect Service
+ *
+ * Contains redirect business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ */
+class RedirectService {
+    constructor(redirectApi) {
+        this.redirectApi = redirectApi;
+    }
+    /** ADMIN: Create a new redirect */
+    async createRedirect(redirect) {
+        return this.redirectApi.createRedirect(redirect);
+    }
+    /** ADMIN: List all redirects for the current tenant */
+    async getRedirects() {
+        return this.redirectApi.getRedirects();
+    }
+    /** ADMIN: Get a redirect by ID */
+    async getRedirectById(redirectId) {
+        return this.redirectApi.getRedirectById(redirectId);
+    }
+    /** ADMIN: Update a redirect's label or target URL */
+    async updateRedirect(redirectId, redirect) {
+        return this.redirectApi.updateRedirect(redirectId, redirect);
+    }
+    /** ADMIN: Soft-delete a redirect */
+    async deleteRedirect(redirectId) {
+        return this.redirectApi.deleteRedirect(redirectId);
+    }
+    /** TENANT ONLY: Get scan analytics for a redirect */
+    async getRedirectAnalytics(redirectId, options) {
+        return this.redirectApi.getRedirectAnalytics(redirectId, options);
+    }
+}
+
+/**
+ * Redirect Manager - Clean, high-level interface for QR code / short-link tracking
+ *
+ * Manages redirects: short-coded links (e.g. printed on QR codes) that resolve
+ * to a target URL and record per-scan analytics (device type, day, channel).
+ *
+ * @group Managers
+ * @category Redirect Management
+ *
+ * @example Basic Redirect Operations
+ * ```typescript
+ * // Create a redirect
+ * const redirect = await sdk.redirects.create({
+ *   targetUrl: 'https://app.pers.ninja/campaigns/abc',
+ *   label: 'Summer Campaign QR'
+ * });
+ *
+ * // Build the QR target URL
+ * const qrUrl = sdk.redirects.getQrUrl(redirect.code);
+ *
+ * // Get scan analytics
+ * const stats = await sdk.redirects.getAnalytics(redirect.id, { from: '2025-01-01' });
+ * ```
+ */
+class RedirectManager {
+    constructor(apiClient, events) {
+        this.apiClient = apiClient;
+        this.events = events;
+        const redirectApi = new RedirectApi(apiClient);
+        this.redirectService = new RedirectService(redirectApi);
+    }
+    /**
+     * ADMIN: Create a new redirect
+     *
+     * @example
+     * ```typescript
+     * const redirect = await sdk.redirects.create({ targetUrl, label: 'Summer QR' });
+     * ```
+     */
+    async create(redirect) {
+        return this.redirectService.createRedirect(redirect);
+    }
+    /**
+     * ADMIN: Get all redirects for the current tenant
+     */
+    async getAll() {
+        return this.redirectService.getRedirects();
+    }
+    /**
+     * ADMIN: Get a redirect by ID
+     */
+    async getById(redirectId) {
+        return this.redirectService.getRedirectById(redirectId);
+    }
+    /**
+     * ADMIN: Update a redirect's label or target URL
+     */
+    async update(redirectId, redirect) {
+        return this.redirectService.updateRedirect(redirectId, redirect);
+    }
+    /**
+     * ADMIN: Soft-delete a redirect
+     */
+    async delete(redirectId) {
+        return this.redirectService.deleteRedirect(redirectId);
+    }
+    /**
+     * TENANT ONLY: Get scan analytics for a redirect
+     *
+     * @param redirectId - UUID of the redirect
+     * @param options - Optional `from`/`to` date range filters
+     *
+     * @example
+     * ```typescript
+     * const stats = await sdk.redirects.getAnalytics(redirect.id, { from: '2025-01-01' });
+     * console.log(stats.total, stats.byDevice);
+     * ```
+     */
+    async getAnalytics(redirectId, options) {
+        return this.redirectService.getRedirectAnalytics(redirectId, options);
+    }
+    /**
+     * Build the public QR target URL for a redirect's code.
+     *
+     * The public endpoint (`GET /redirects/go/:code`) requires no auth and issues
+     * a 302 to the redirect's `targetUrl`.
+     */
+    getQrUrl(code) {
+        return `${this.apiClient.getApiRoot()}/redirects/go/${code}`;
+    }
+}
+
 /**
  * Webhook API - Low-level API client for webhook operations
  *
@@ -20386,7 +21802,7 @@ class WebhookManager {
  */
 const DEFAULT_CONFIG = {
     autoReconnect: true,
-    maxReconnectAttempts: 10,
+    maxReconnectAttempts: Infinity,
     reconnectDelay: 1000,
     connectionTimeout: 30000,
     debug: false,
@@ -20402,8 +21818,13 @@ class PersEventsClient {
         // Event handlers by type
         this.handlers = new Map();
         this.stateHandlers = new Set();
+        this.notificationHandlers = new Set();
         // Connection info from server
         this.connectionInfo = null;
+        // Notification routing context (channelId + topicIds), resolved server-side by the relay
+        this.notificationContext = { notificationChannelId: null, topicIds: [] };
+        // Explicit channelId to (re-)bind on next connect, set via bindNotificationChannel() before connect resolves
+        this.pendingNotificationChannelId = null;
         // Current subscription state
         this.subscriptionState = { wallets: [], chains: [], activeChains: [] };
         // Pending subscription promise resolver
@@ -20430,6 +21851,9 @@ class PersEventsClient {
                 this.cleanup();
                 this.setState('error');
                 reject(new Error(`Connection timeout after ${this.config.connectionTimeout}ms`));
+                // Trigger auto-reconnect: cleanup() nullified ws.onclose so it won't fire.
+                // Without this call, a timed-out initial connection silently dies with no retry.
+                this.handleDisconnect();
             }, this.config.connectionTimeout);
             const clearTimeoutAndResolve = () => {
                 clearTimeout(connectionTimeout);
@@ -20530,6 +21954,52 @@ class PersEventsClient {
         return { ...this.subscriptionState };
     }
     // ─────────────────────────────────────────────────────────────────────────────
+    // Notifications (Flow 1 — personal channel real-time wake signal)
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Bind this socket to a personal notification channelId (from `GET /notifications/channel-id`).
+     *
+     * The relay auto-resolves the channelId server-side on connect, so this is an optimization
+     * for immediate binding rather than a requirement — safe to call any time after connect().
+     * If not yet connected, the channelId is sent as soon as the connection opens.
+     */
+    bindNotificationChannel(channelId, topicIds) {
+        this.pendingNotificationChannelId = channelId;
+        if (this.state !== 'connected' || !this.ws)
+            return;
+        const message = { type: 'subscribe', notificationChannelId: channelId, ...(topicIds ? { topicIds } : {}) };
+        this.ws.send(JSON.stringify(message));
+        this.log('Sent notification channel bind:', message);
+    }
+    /**
+     * Rebind the personal notification channelId on an already-connected socket
+     * (e.g. after re-auth resolves a new channelId).
+     */
+    updateNotificationChannel(channelId) {
+        this.pendingNotificationChannelId = channelId;
+        if (this.state !== 'connected' || !this.ws)
+            return;
+        const message = { type: 'subscription.updated', notificationChannelId: channelId };
+        this.ws.send(JSON.stringify(message));
+        this.log('Sent notification channel update:', message);
+    }
+    /**
+     * Get the notification routing context (channelId + topicIds) resolved for this socket.
+     */
+    getNotificationContext() {
+        return { ...this.notificationContext };
+    }
+    /**
+     * Subscribe to real-time notification wake signals.
+     *
+     * The signal carries no notification content — always follow up with
+     * `sdk.notifications.list()` / `getUnreadCount()`.
+     */
+    onNotificationPending(handler) {
+        this.notificationHandlers.add(handler);
+        return () => { this.notificationHandlers.delete(handler); };
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
     // Event Handlers
     // ─────────────────────────────────────────────────────────────────────────────
     /**
@@ -20623,15 +22093,29 @@ class PersEventsClient {
             switch (message.type) {
                 case 'connected':
                     this.connectionInfo = message.payload;
+                    this.notificationContext = {
+                        notificationChannelId: message.payload.notificationChannelId ?? null,
+                        topicIds: message.payload.topicIds ?? [],
+                    };
                     this.reconnectAttempts = 0;
                     this.setState('connected');
                     this.log('Connected:', message.payload);
                     onConnected?.();
                     // Restore subscriptions on reconnect
                     this.restoreSubscriptions();
+                    // Re-bind an explicitly-set notification channel (overrides the relay's auto-resolved one)
+                    if (this.pendingNotificationChannelId) {
+                        this.bindNotificationChannel(this.pendingNotificationChannelId);
+                    }
                     break;
                 case 'subscribed':
                     this.subscriptionState = message.payload;
+                    if (message.payload.notificationChannelId !== undefined || message.payload.topicIds !== undefined) {
+                        this.notificationContext = {
+                            notificationChannelId: message.payload.notificationChannelId ?? this.notificationContext.notificationChannelId,
+                            topicIds: message.payload.topicIds ?? this.notificationContext.topicIds,
+                        };
+                    }
                     this.log('Subscription confirmed:', message.payload);
                     this.pendingSubscription?.resolve();
                     break;
@@ -20643,6 +22127,9 @@ class PersEventsClient {
                 case 'event':
                     this.routeEvent(message.payload);
                     break;
+                case 'notification.pending':
+                    this.routeNotification(message.payload);
+                    break;
                 case 'ping':
                     // Respond to server ping with pong
                     this.sendPong();
@@ -20708,6 +22195,17 @@ class PersEventsClient {
             }
         });
     }
+    routeNotification(info) {
+        this.log('Notification pending:', info);
+        this.notificationHandlers.forEach(handler => {
+            try {
+                handler(info);
+            }
+            catch (err) {
+                console.error('[PERS-Events] Notification handler error:', err);
+            }
+        });
+    }
     handleDisconnect() {
         this.cleanup();
         this.setState('disconnected');
@@ -20716,8 +22214,8 @@ class PersEventsClient {
                 this.attemptReconnect();
             }
             else {
+                // maxReconnectAttempts exceeded (only reachable if explicitly set to a finite number)
                 this.log(`Max reconnect attempts (${this.config.maxReconnectAttempts}) reached. Call connect() manually to retry.`);
-                // Reset counter so manual connect() will work
                 this.reconnectAttempts = 0;
             }
         }
@@ -20726,7 +22224,10 @@ class PersEventsClient {
         const delay = Math.min(this.config.reconnectDelay * Math.pow(2, this.reconnectAttempts), 30000 // Max 30 second delay
         );
         this.reconnectAttempts++;
-        this.log(`🔄 Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.config.maxReconnectAttempts})`);
+        const attemptLabel = isFinite(this.config.maxReconnectAttempts)
+            ? `${this.reconnectAttempts}/${this.config.maxReconnectAttempts}`
+            : `${this.reconnectAttempts}`;
+        this.log(`🔄 Reconnecting in ${delay}ms (attempt ${attemptLabel})`);
         this.setState('reconnecting');
         this.reconnectTimeout = setTimeout(async () => {
             try {
@@ -20836,6 +22337,8 @@ class WalletEventsManager {
         this.eventEmitter = eventEmitter;
         this.client = null;
         this.pendingHandlers = [];
+        this.pendingNotificationHandlers = [];
+        this.pendingNotificationChannelId = null;
         this.unsubscribes = [];
         // Track if WS gave up reconnecting (so we can retry on token refresh)
         this.reconnectGaveUp = false;
@@ -20864,8 +22367,9 @@ class WalletEventsManager {
      * For auto-subscription, use `sdk.connectWalletEvents()` instead.
      */
     async connect() {
-        // Already connected?
-        if (this.client?.getState() === 'connected') {
+        // Return early if already active — don't discard an in-progress connection
+        const currentState = this.client?.getState();
+        if (currentState === 'connected' || currentState === 'connecting' || currentState === 'reconnecting') {
             return;
         }
         const sdkConfig = this.apiClient.getConfig();
@@ -20899,44 +22403,63 @@ class WalletEventsManager {
             debug: this.config.debug,
             tokenRefresher,
         });
-        await this.client.connect(token);
-        // Reset gave-up flag on successful connection
-        this.reconnectGaveUp = false;
-        // Track previous state to detect reconnections and give-ups
-        let previousState = 'connected';
+        // ── Wire up all handlers BEFORE connecting ────────────────────────────
+        // This ensures state changes and events are captured even if the initial
+        // connect() times out and PersEventsClient retries in the background.
         // Clean up previous state change listener (prevent duplicate listeners)
         this.stateChangeUnsubscribe?.();
-        // Listen for state changes
+        // Track whether a reconnect cycle is in progress.
+        // Cannot use previousState === 'reconnecting' because PersEventsClient emits
+        // 'connecting' between 'reconnecting' and 'connected', stomping previousState.
+        let wasReconnecting = false;
         this.stateChangeUnsubscribe = this.client.onStateChange((state) => {
-            if (state === 'disconnected' && previousState === 'reconnecting') {
-                // Transitioned from reconnecting to disconnected = exhausted all attempts
+            if (state === 'reconnecting') {
+                wasReconnecting = true;
+            }
+            else if (state === 'disconnected' && wasReconnecting) {
+                // Exhausted all reconnect attempts
                 this.reconnectGaveUp = true;
+                wasReconnecting = false;
             }
             else if (state === 'connected') {
                 this.reconnectGaveUp = false;
-                // Emit reconnected event so apps can refresh state (catch missed events)
-                if (previousState === 'reconnecting') {
+                if (wasReconnecting) {
+                    wasReconnecting = false;
+                    // Emit reconnected event so apps can refresh state (catch missed events)
+                    // and re-subscribe wallets if the initial subscription never completed.
                     this.eventEmitter.emitSuccess({
                         type: 'wallet_reconnected',
                         domain: 'wallet',
                         userMessage: 'Wallet events reconnected',
-                        details: { previousState }
+                        details: {}
                     });
                 }
             }
-            previousState = state;
         });
         // Clear previous unsubscribes on new connection (prevent memory leak)
         this.unsubscribes.forEach(unsub => unsub());
         this.unsubscribes = [];
         // Route all events through PersEventEmitter for unified stream
         // Note: Cast needed because web3-types uses string for event.type while pers-shared uses strict union
-        this.client.on('*', (event) => this.emitToPersEvents(event));
+        this.unsubscribes.push(this.client.on('*', (event) => this.emitToPersEvents(event)));
         // Re-attach any handlers registered before connect
         for (const { type, handler } of this.pendingHandlers) {
             this.unsubscribes.push(this.client.on(type, handler));
         }
         this.pendingHandlers = [];
+        // Re-attach any notification handlers registered before connect
+        for (const handler of this.pendingNotificationHandlers) {
+            this.unsubscribes.push(this.client.onNotificationPending(handler));
+        }
+        this.pendingNotificationHandlers = [];
+        // Rebind an explicitly-set notification channel across reconnects (new client instance each time)
+        if (this.pendingNotificationChannelId) {
+            this.client.bindNotificationChannel(this.pendingNotificationChannelId);
+        }
+        // ─────────────────────────────────────────────────────────────────────
+        await this.client.connect(token);
+        // Reset gave-up flag on successful initial connection
+        this.reconnectGaveUp = false;
     }
     /**
      * Disconnect from real-time events
@@ -20961,6 +22484,8 @@ class WalletEventsManager {
         this.authEventUnsubscribe = undefined;
         this.reconnectGaveUp = false;
         this.lastSubscriptions = { wallets: [], chains: [] };
+        this.pendingNotificationHandlers = [];
+        this.pendingNotificationChannelId = null;
     }
     // ─────────────────────────────────────────────────────────────────────────────
     // Subscription Methods (v1.2.0)
@@ -21046,6 +22571,47 @@ class WalletEventsManager {
         return this.client?.getSubscriptionState() ?? { wallets: [], chains: [], activeChains: [] };
     }
     // ─────────────────────────────────────────────────────────────────────────────
+    // Notifications (Flow 1 — shares this same socket, see NotificationManager)
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Bind this socket to a personal notification channelId (from `sdk.notifications.getChannelId()`).
+     * Safe to call before or after connect() — queued and sent once the socket is open.
+     */
+    bindNotificationChannel(channelId, topicIds) {
+        this.pendingNotificationChannelId = channelId;
+        this.client?.bindNotificationChannel(channelId, topicIds);
+    }
+    /**
+     * Rebind the personal notification channelId on an already-connected socket.
+     */
+    updateNotificationChannel(channelId) {
+        this.pendingNotificationChannelId = channelId;
+        this.client?.updateNotificationChannel(channelId);
+    }
+    /**
+     * Get the notification routing context (channelId + topicIds) resolved for this socket.
+     */
+    getNotificationContext() {
+        return this.client?.getNotificationContext() ?? { notificationChannelId: null, topicIds: [] };
+    }
+    /**
+     * Subscribe to real-time notification wake signals (`notification.pending`).
+     * The signal carries no content — always follow up with `sdk.notifications.list()`.
+     */
+    onNotificationPending(handler) {
+        if (this.client) {
+            const unsub = this.client.onNotificationPending(handler);
+            this.unsubscribes.push(unsub);
+            return unsub;
+        }
+        this.pendingNotificationHandlers.push(handler);
+        return () => {
+            const idx = this.pendingNotificationHandlers.indexOf(handler);
+            if (idx !== -1)
+                this.pendingNotificationHandlers.splice(idx, 1);
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
     // Event Handlers
     // ─────────────────────────────────────────────────────────────────────────────
     /**
@@ -21208,6 +22774,263 @@ class WalletEventsManager {
     }
 }
 
+/**
+ * Notification API - Low-level API client for the notification inbox
+ *
+ * Backend routes (`src/notification/infrastructure/notifications.controller.ts`):
+ * - `GET /notifications/channel-id` - Besu channelId for real-time WS binding
+ * - `GET /notifications` - paginated inbox
+ * - `GET /notifications/unread-count` - unread badge count
+ * - `PATCH /notifications/:id/read` - mark as read
+ * - `DELETE /notifications/:id` - delete
+ * - `POST /notifications/send` - direct push (BUSINESS → USER, TENANT → USER|BUSINESS)
+ *
+ * @internal Use NotificationService or NotificationManager for higher-level operations
+ */
+class NotificationApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/notifications';
+    }
+    /**
+     * Get the Besu channelId for the authenticated account (auto-provisioned on first call).
+     * GET /notifications/channel-id
+     */
+    async getChannelId() {
+        const res = await this.apiClient.get(`${this.basePath}/channel-id`);
+        return res.channelId;
+    }
+    /**
+     * List the authenticated account's notification inbox (paginated).
+     * GET /notifications
+     */
+    async list(options) {
+        const params = new URLSearchParams();
+        if (options?.category)
+            params.append('category', options.category);
+        if (options?.unreadOnly !== undefined)
+            params.append('unreadOnly', String(options.unreadOnly));
+        if (options?.page)
+            params.append('page', String(options.page));
+        if (options?.limit)
+            params.append('limit', String(options.limit));
+        const queryString = params.toString();
+        const url = queryString ? `${this.basePath}?${queryString}` : this.basePath;
+        return this.apiClient.get(url);
+    }
+    /**
+     * Get unread notification count.
+     * GET /notifications/unread-count
+     */
+    async getUnreadCount() {
+        return this.apiClient.get(`${this.basePath}/unread-count`);
+    }
+    /**
+     * Mark a notification as read.
+     * PATCH /notifications/:id/read
+     */
+    async markAsRead(id) {
+        return this.apiClient.patch(`${this.basePath}/${id}/read`);
+    }
+    /**
+     * Delete a notification.
+     * DELETE /notifications/:id
+     */
+    async delete(id) {
+        await this.apiClient.delete(`${this.basePath}/${id}`);
+    }
+    /**
+     * Send a direct notification (BUSINESS → USER, or TENANT → USER|BUSINESS).
+     * POST /notifications/send
+     */
+    async send(dto) {
+        return this.apiClient.post(`${this.basePath}/send`, dto);
+    }
+}
+
+/**
+ * Notification Service - Business logic layer for the notification inbox
+ *
+ * Caches the resolved `channelId` per session (stable per-recipient per-tenant,
+ * per the SDK integration guide) to avoid refetching it on every WS (re)connect.
+ *
+ * @group Services
+ * @category Notification
+ */
+class NotificationService {
+    constructor(notificationApi) {
+        this.notificationApi = notificationApi;
+    }
+    /**
+     * Get the Besu channelId for the authenticated account.
+     * Cached in-memory for the lifetime of this service instance.
+     */
+    async getChannelId(forceRefresh = false) {
+        if (!forceRefresh && this.cachedChannelId !== undefined) {
+            return this.cachedChannelId;
+        }
+        this.cachedChannelId = await this.notificationApi.getChannelId();
+        return this.cachedChannelId;
+    }
+    async getNotifications(options) {
+        return this.notificationApi.list(options);
+    }
+    async getUnreadCount() {
+        return this.notificationApi.getUnreadCount();
+    }
+    async markAsRead(id) {
+        if (!id?.trim()) {
+            throw new Error('Notification id is required');
+        }
+        return this.notificationApi.markAsRead(id);
+    }
+    async deleteNotification(id) {
+        if (!id?.trim()) {
+            throw new Error('Notification id is required');
+        }
+        return this.notificationApi.delete(id);
+    }
+    async sendNotification(dto) {
+        if (!dto.recipientId?.trim()) {
+            throw new Error('recipientId is required');
+        }
+        if (!dto.title?.trim()) {
+            throw new Error('title is required');
+        }
+        return this.notificationApi.send(dto);
+    }
+}
+
+/**
+ * Notification Manager - Clean, high-level interface for the notification inbox (Flow 1)
+ *
+ * Notifications are delivered through two independent channels — use both together:
+ * - **REST inbox** (this manager): source of truth, full content, pagination, read/unread state
+ * - **WS Relay `notification.pending`** (`onPending()`): real-time wake signal, no content —
+ *   always follow up with a REST fetch
+ *
+ * Real-time delivery **shares the same WebSocket connection** as `sdk.walletEvents` — no
+ * second socket is opened. Call `connectRealtime()` once (after auth) to bind the channel.
+ *
+ * @group Managers
+ * @category Notification
+ *
+ * @example Recommended app flow
+ * ```typescript
+ * await sdk.notifications.connectRealtime();
+ * const inbox = await sdk.notifications.list({ unreadOnly: true });
+ * const { count } = await sdk.notifications.getUnreadCount();
+ *
+ * sdk.notifications.onPending(async () => {
+ *   // Signal is a hint — always re-fetch for actual content
+ *   await sdk.notifications.list();
+ *   await sdk.notifications.getUnreadCount();
+ * });
+ * ```
+ *
+ * @example Business → user direct push
+ * ```typescript
+ * await sdk.notifications.send({
+ *   recipientType: 'user',
+ *   recipientId: userId,
+ *   title: 'New reward available!',
+ *   body: "You've earned 100 points.",
+ *   category: 'campaign',
+ *   entityId: campaignId,
+ * });
+ * ```
+ */
+class NotificationManager {
+    constructor(apiClient, walletEvents, events) {
+        this.walletEvents = walletEvents;
+        this.events = events;
+        this.notificationService = new NotificationService(new NotificationApi(apiClient));
+    }
+    // ================================
+    // REST Inbox
+    // ================================
+    /**
+     * Get the Besu channelId for the authenticated account (auto-provisioned on first call).
+     * Cached in-memory; pass `forceRefresh` to bypass the cache (e.g. after re-auth).
+     */
+    async getChannelId(forceRefresh = false) {
+        return this.notificationService.getChannelId(forceRefresh);
+    }
+    /**
+     * List the authenticated account's notification inbox (paginated).
+     */
+    async list(options) {
+        return this.notificationService.getNotifications(options);
+    }
+    /**
+     * Get unread notification count (for a badge).
+     */
+    async getUnreadCount() {
+        return this.notificationService.getUnreadCount();
+    }
+    /**
+     * Mark a notification as read.
+     */
+    async markAsRead(id) {
+        return this.notificationService.markAsRead(id);
+    }
+    /**
+     * Delete a notification.
+     */
+    async delete(id) {
+        return this.notificationService.deleteNotification(id);
+    }
+    /**
+     * Send a direct notification. BUSINESS accounts may only target `recipientType: 'user'`;
+     * TENANT (admin) accounts may target `'user'` or `'business'`.
+     */
+    async send(dto) {
+        const result = await this.notificationService.sendNotification(dto);
+        this.events?.emitSuccess({
+            domain: 'notification',
+            type: 'notification_sent',
+            userMessage: 'Notification sent successfully',
+            details: { notificationId: result.id, recipientType: result.recipientType }
+        });
+        return result;
+    }
+    // ================================
+    // Real-Time (shares sdk.walletEvents' socket)
+    // ================================
+    /**
+     * Resolve this account's channelId and bind it on the shared wallet-events socket,
+     * connecting first if needed. Call once after authentication.
+     */
+    async connectRealtime() {
+        await this.walletEvents.connect();
+        const channelId = await this.getChannelId();
+        if (channelId) {
+            this.walletEvents.bindNotificationChannel(channelId);
+        }
+    }
+    /**
+     * Get the notification routing context (channelId + topicIds) resolved for the socket.
+     */
+    getNotificationContext() {
+        return this.walletEvents.getNotificationContext();
+    }
+    /**
+     * Subscribe to real-time notification wake signals (`notification.pending`).
+     * The signal carries no content — always follow up with `list()` / `getUnreadCount()`.
+     */
+    onPending(handler) {
+        return this.walletEvents.onNotificationPending((info) => {
+            this.events?.emitSuccess({
+                domain: 'notification',
+                type: 'notification_pending',
+                userMessage: 'A new notification arrived',
+                details: { messageId: info.messageId, category: info.notificationCategory }
+            });
+            handler(info);
+        });
+    }
+}
+
 /**
  * Custom Field Definitions API
  *
@@ -21225,11 +23048,12 @@ class CustomFieldApi {
      * List all custom field definitions
      * Backend returns non-paginated array sorted by sortOrder
      */
-    async getDefinitions(entityType) {
+    async getDefinitions(entityType, include) {
         const params = new URLSearchParams();
         if (entityType) {
             params.append('entityType', entityType);
         }
+        setIncludeParam(params, include);
         const query = params.toString();
         const url = query ? `${this.basePath}?${query}` : this.basePath;
         return this.apiClient.get(url);
@@ -21237,8 +23061,11 @@ class CustomFieldApi {
     /**
      * Get a single custom field definition by ID
      */
-    async getDefinition(id) {
-        return this.apiClient.get(`${this.basePath}/${id}`);
+    async getDefinition(id, include) {
+        const params = new URLSearchParams();
+        setIncludeParam(params, include);
+        const query = params.toString();
+        return this.apiClient.get(`${this.basePath}/${id}${query ? `?${query}` : ''}`);
     }
     /**
      * Create a new custom field definition
@@ -21350,7 +23177,7 @@ class CustomFieldDefinitionManager {
      * ```
      */
     async getDefinitions(options) {
-        return this.api.getDefinitions(options?.entityType);
+        return this.api.getDefinitions(options?.entityType, options?.include);
     }
     /**
      * Get a single custom field definition by ID
@@ -21371,8 +23198,8 @@ class CustomFieldDefinitionManager {
      * }
      * ```
      */
-    async getDefinition(id) {
-        return this.api.getDefinition(id);
+    async getDefinition(id, include) {
+        return this.api.getDefinition(id, include);
     }
     /**
      * Create a new custom field definition
@@ -22233,6 +24060,16 @@ class PersSDK {
                     console.warn('[PersSDK] Failed to auto-connect wallet events:', err.message);
                 });
             }
+            // Re-subscribe after reconnect. This covers two cases:
+            // 1. Normal reconnect after a drop (restoreSubscriptions handles it, but this
+            //    also refreshes the subscription from the latest user state).
+            // 2. Initial connection timed out → client auto-reconnected → subscription
+            //    was never sent because connectWalletEvents() failed before subscribeWallets().
+            if (event.level === 'success' && event.type === 'wallet_reconnected') {
+                this.connectWalletEvents().catch((err) => {
+                    console.warn('[PersSDK] Failed to re-subscribe wallet events after reconnect:', err.message);
+                });
+            }
             // Disconnect on logout
             if (event.level === 'success' && event.type === 'logout_success') {
                 this.walletEvents.disconnect();
@@ -22640,6 +24477,18 @@ class PersSDK {
         }
         return this._tenants;
     }
+    /**
+     * IPFS manager - Gateway, URL and token metadata resolution (chain-agnostic, no web3 dependencies)
+     *
+     * @example
+     * ```typescript
+     * const url = await sdk.ipfs.resolveUrl('ipfs://QmXxx...');
+     * const metadata = await sdk.ipfs.fetchMetadata('ipfs://QmXxx.../metadata.json');
+     * ```
+     */
+    get ipfs() {
+        return this.tenants.ipfs;
+    }
     /**
      * API Key manager - High-level API key management operations (Admin Only)
      *
@@ -22729,6 +24578,35 @@ class PersSDK {
         }
         return this._triggerSources;
     }
+    /**
+     * Redirect manager - High-level redirect (QR code / short-link) operations
+     *
+     * Provides methods for creating short-code redirects, updating their target
+     * URL/label, and retrieving per-scan analytics (device, day, channel breakdowns).
+     *
+     * @returns RedirectManager instance
+     *
+     * @example Redirect Operations
+     * ```typescript
+     * // Create a redirect
+     * const redirect = await sdk.redirects.create({
+     *   targetUrl: 'https://app.pers.ninja/campaigns/abc',
+     *   label: 'Summer Campaign QR'
+     * });
+     *
+     * // Build the QR target URL
+     * const qrUrl = sdk.redirects.getQrUrl(redirect.code);
+     *
+     * // Get scan analytics
+     * const stats = await sdk.redirects.getAnalytics(redirect.id, { from: '2025-01-01' });
+     * ```
+     */
+    get redirects() {
+        if (!this._redirects) {
+            this._redirects = new RedirectManager(this.apiClient, this._events);
+        }
+        return this._redirects;
+    }
     /**
      * Webhook manager - High-level webhook operations
      *
@@ -22898,6 +24776,39 @@ class PersSDK {
         // Reset manager so it picks up new config
         this._walletEvents = undefined;
     }
+    /**
+     * Notification Manager - Per-recipient notification inbox (Flow 1 — transactional/private)
+     *
+     * Notifications are delivered through two independent channels — use both together:
+     * - **REST inbox** (`list`, `getUnreadCount`, `markAsRead`, `delete`): source of truth
+     * - **WS Relay `notification.pending`** (`onPending`): real-time wake signal only
+     *
+     * Real-time delivery shares the same WebSocket connection as `sdk.walletEvents` —
+     * calling `connectRealtime()` connects it (if needed) and binds the channelId.
+     *
+     * @returns NotificationManager instance
+     *
+     * @example Basic Usage
+     * ```typescript
+     * await sdk.notifications.connectRealtime();
+     *
+     * const inbox = await sdk.notifications.list({ unreadOnly: true });
+     * const { count } = await sdk.notifications.getUnreadCount();
+     *
+     * sdk.notifications.onPending(() => {
+     *   // Signal carries no content — re-fetch the inbox
+     *   sdk.notifications.list();
+     * });
+     * ```
+     *
+     * @see {@link NotificationManager} for detailed documentation
+     */
+    get notifications() {
+        if (!this._notifications) {
+            this._notifications = new NotificationManager(this.apiClient, this.walletEvents, this._events);
+        }
+        return this._notifications;
+    }
     // ==========================================
     // DATA SOURCE TRACKING
     // ==========================================
@@ -22966,6 +24877,30 @@ class PersSDK {
     setPlatform(platform) {
         this.apiClient.setPlatform(platform);
     }
+    // ==========================================
+    // CONTENT LOCALE
+    // ==========================================
+    /**
+     * Set the content locale for localized API responses and IPFS token metadata
+     *
+     * Opt-in: until set (or configured via `PersConfig.locale`), base-language strings are returned.
+     * Already-loaded content is not re-translated: refetch (or invalidate app caches) after changing it.
+     *
+     * @param locale - A BCP 47 tag (e.g. 'de-DE'), 'auto' for the device locale, or null to disable
+     *
+     * @example
+     * ```typescript
+     * sdk.setLocale('fr-FR');
+     * const campaigns = await sdk.campaigns.getActiveCampaigns();
+     * ```
+     */
+    setLocale(locale) {
+        this.apiClient.setLocale(locale);
+    }
+    /** Normalized content locale in effect, or null when disabled */
+    getLocale() {
+        return this.apiClient.getLocale();
+    }
     /**
      * Gets the API client for direct PERS API requests
      *
@@ -23373,17 +25308,30 @@ class ReactNativeSecureStorage {
     async get(key) {
         const prefixedKey = this.getKeyName(key);
         if (this.SECURE_KEYS.has(key)) {
-            try {
-                if (Keychain) {
-                    const credentials = await Keychain.getGenericPassword({ service: prefixedKey });
-                    if (credentials) {
-                        return this.tryParse(credentials.password);
+            // The iOS Keychain can be briefly unreadable (device locked, background launch), so retry before giving up
+            let keychainError;
+            if (Keychain) {
+                for (let attempt = 0; attempt < 3; attempt++) {
+                    try {
+                        const credentials = await Keychain.getGenericPassword({ service: prefixedKey });
+                        if (credentials) {
+                            return this.tryParse(credentials.password);
+                        }
+                        keychainError = undefined;
+                        break;
+                    }
+                    catch (e) {
+                        keychainError = e;
+                        if (attempt < 2)
+                            await new Promise(resolve => setTimeout(resolve, 150 * (attempt + 1)));
                     }
                 }
             }
-            catch (e) {
-                console.warn(`[ReactNativeSecureStorage] Failed to access keychain for ${key}`, e);
-                // Continue to fallback check...
+            if (keychainError) {
+                console.warn(`[ReactNativeSecureStorage] Failed to access keychain for ${key}`, keychainError);
+                // Returning "missing" here would make the DPoP manager regenerate the key pair and log the user out
+                if (key === DPOP_STORAGE_KEYS.PRIVATE)
+                    throw keychainError;
             }
             // Fallback: Check AsyncStorage if not found in Keychain or Keychain failed
             try {
@@ -23718,6 +25666,9 @@ class ReactNativeHttpClient {
     async put(url, body, options) {
         return this.request('PUT', url, body, options);
     }
+    async patch(url, body, options) {
+        return this.request('PATCH', url, body, options);
+    }
     async delete(url, options) {
         return this.request('DELETE', url, undefined, options);
     }
@@ -23736,8 +25687,8 @@ class ReactNativeHttpClient {
             config.signal = controller.signal;
             setTimeout(() => controller.abort(), options.timeout);
         }
-        // Add body for POST/PUT requests
-        if (body && (method === 'POST' || method === 'PUT')) {
+        // Add body for POST/PUT/PATCH requests
+        if (body && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
             config.body = JSON.stringify(body);
         }
         try {
@@ -23893,6 +25844,7 @@ const PersSDKProvider = ({ children, config }) => {
     const [isInitialized, setIsInitialized] = react.useState(false);
     const [isAuthenticated, setIsAuthenticated] = react.useState(false);
     const [user, setUser] = react.useState(null);
+    const [locale, setLocaleState] = react.useState(null);
     // Keep state refs in sync immediately (not in useEffect to avoid race conditions)
     sdkRef.current = sdk;
     isInitializedRef.current = isInitialized;
@@ -23970,6 +25922,7 @@ const PersSDKProvider = ({ children, config }) => {
             }, { domains: ['authentication'], replay: true });
             setAuthProvider(authProvider);
             setSdk(sdkInstance);
+            setLocaleState(sdkInstance.getLocale());
             setIsInitialized(true);
         }
         catch (error) {
@@ -24002,6 +25955,14 @@ const PersSDKProvider = ({ children, config }) => {
             });
         }
     }, [config, isInitialized, initialize]);
+    const setLocale = react.useCallback((next) => {
+        const currentSdk = sdkRef.current;
+        if (!currentSdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        currentSdk.setLocale(next);
+        setLocaleState(currentSdk.getLocale());
+    }, []);
     const refreshUserData = react.useCallback(async () => {
         // Read from refs to get current values
         const currentSdk = sdkRef.current;
@@ -24068,8 +26029,10 @@ const PersSDKProvider = ({ children, config }) => {
         isInitialized,
         isAuthenticated,
         user,
+        locale,
         // Methods - expose functions directly, not through refs
         initialize,
+        setLocale,
         setAuthenticationState,
         refreshUserData,
         restoreSession,
@@ -24079,7 +26042,9 @@ const PersSDKProvider = ({ children, config }) => {
         isInitialized,
         isAuthenticated,
         user,
+        locale,
         initialize,
+        setLocale,
         setAuthenticationState,
         refreshUserData,
         restoreSession
@@ -44438,9 +46403,9 @@ class Web3ChainService {
  * - Metadata: CACHED 24h - IPFS content is immutable
  */
 class TokenDomainService {
-    constructor(web3Api, metadataService, contractService) {
+    constructor(web3Api, metadataSource, contractService) {
         this.web3Api = web3Api;
-        this.metadataService = metadataService;
+        this.metadataSource = metadataSource;
         this.contractService = contractService;
         this.cache = globalCacheService.createNamespace('token-domain');
     }
@@ -44461,7 +46426,7 @@ class TokenDomainService {
                 const abi = convertAbiToInterface(params.abi);
                 const tokenUri = await this.web3Api.getTokenUri({ ...params, abi });
                 const metadata = tokenUri
-                    ? await this.metadataService.fetchAndProcessMetadata(tokenUri)
+                    ? await this.metadataSource.fetchAndProcessMetadata(tokenUri)
                     : null;
                 return { tokenId: params.tokenId, tokenUri, metadata };
             }
@@ -44643,47 +46608,6 @@ class TokenDomainService {
     }
 }
 
-/**
- * MetadataDomainService - Clean IPFS metadata resolution with centralized caching
- *
- * IPFS gateway is resolved from tenant configuration (chain-agnostic).
- */
-class MetadataDomainService {
-    constructor(ipfsApi) {
-        this.ipfsApi = ipfsApi;
-        this.cache = globalCacheService.createNamespace('metadata');
-    }
-    async fetchAndProcessMetadata(tokenUri) {
-        const cacheKey = `fetch:${tokenUri}`;
-        return this.cache.getOrSet(cacheKey, async () => {
-            try {
-                return await this.ipfsApi.fetchAndProcessMetadata(tokenUri);
-            }
-            catch (error) {
-                console.error(`Error fetching metadata for ${tokenUri}:`, error);
-                return null;
-            }
-        }, CacheTTL.METADATA);
-    }
-    async resolveIPFSUrl(url) {
-        const cacheKey = `resolve:${url}`;
-        return this.cache.getOrSet(cacheKey, () => this.ipfsApi.resolveIPFSUrl(url), CacheTTL.GATEWAY);
-    }
-    /**
-     * Get IPFS gateway domain from tenant configuration.
-     * Useful for pipes that need to resolve URLs synchronously after initial fetch.
-     */
-    async getIpfsGatewayDomain() {
-        return this.ipfsApi.getIpfsGatewayDomain();
-    }
-    /**
-     * Clear all cached metadata and URLs for this service
-     */
-    clearCache() {
-        this.cache.clear();
-    }
-}
-
 /**
  * ContractDomainService - Clean contract analysis without external dependencies
  */
@@ -44761,7 +46685,8 @@ class TokenCollectionManager {
         this.config = {
             autoRefreshOnWalletEvents: config?.autoRefreshOnWalletEvents ?? true,
             eventDebounceMs: config?.eventDebounceMs ?? 500,
-            debug: config?.debug ?? false
+            debug: config?.debug ?? false,
+            getLocale: config?.getLocale ?? (() => null)
         };
         if (this.config.autoRefreshOnWalletEvents && eventEmitter) {
             this.setupEventSubscription();
@@ -44791,10 +46716,10 @@ class TokenCollectionManager {
         // Return cached if available and not stale
         if (cached?.lastCollection) {
             this.log(`Cache HIT for ${key}`);
-            return cached.lastCollection;
+            return localizeTokenCollection(cached.lastCollection, this.config.getLocale());
         }
         this.log(`Cache MISS for ${key}, fetching...`);
-        return this.fetchAndCache(params);
+        return localizeTokenCollection(await this.fetchAndCache(params), this.config.getLocale());
     }
     /**
      * Force refresh a specific collection
@@ -44836,7 +46761,7 @@ class TokenCollectionManager {
         return Array.from(this.collections.entries()).map(([_, entry]) => ({
             contractAddress: entry.params.contractAddress,
             accountAddress: entry.params.accountAddress,
-            collection: entry.lastCollection
+            collection: entry.lastCollection ? localizeTokenCollection(entry.lastCollection, this.config.getLocale()) : null
         }));
     }
     /**
@@ -44957,7 +46882,7 @@ class TokenCollectionManager {
             // Notify subscribers
             for (const handler of this.handlers) {
                 try {
-                    handler(newCollection, entry.params.contractAddress, {
+                    handler(localizeTokenCollection(newCollection, this.config.getLocale()), entry.params.contractAddress, {
                         type: source === 'refresh' ? 'refresh' : 'wallet_event',
                         source
                     });
@@ -45342,23 +47267,25 @@ class BalanceManager {
  * Simplified architecture with concrete classes
  */
 class Web3ApplicationService {
-    constructor(web3Api, ipfsApi) {
+    constructor(web3Api, ipfsApi, getLocale = () => null) {
+        this.ipfsApi = ipfsApi;
+        this.getLocale = getLocale;
         // Create domain services with injected infrastructure dependencies
         this.contractDomainService = new ContractDomainService();
-        this.metadataDomainService = new MetadataDomainService(ipfsApi);
-        this.tokenDomainService = new TokenDomainService(web3Api, this.metadataDomainService, this.contractDomainService);
+        this.tokenDomainService = new TokenDomainService(web3Api, this.ipfsApi, this.contractDomainService);
     }
     /**
      * Get balance and metadata for a specific token
      */
     async getSpecificTokenBalance(request) {
-        return this.tokenDomainService.getSpecificTokenBalance({
+        const balance = await this.tokenDomainService.getSpecificTokenBalance({
             accountAddress: request.accountAddress || '',
             contractAddress: request.contractAddress,
             abi: request.abi,
             tokenId: request.tokenId || '',
             chainId: request.chainId
         });
+        return localizeTokenBalance(balance, this.getLocale());
     }
     /**
      * Get metadata for a specific token from on-chain.
@@ -45378,14 +47305,15 @@ class Web3ApplicationService {
             tokenId: request.tokenId || '',
             chainId: request.chainId
         });
-        // Metadata is already normalized at infrastructure layer
-        return domainResult.metadata;
+        // Metadata is already normalized at infrastructure layer; the cache holds the raw JSON,
+        // so the language is applied here, at read time
+        return domainResult.metadata ? localizeTokenMetadata(domainResult.metadata, this.getLocale()) : null;
     }
     /**
      * Retrieve entire collection of tokens with balance and metadata
      */
     async getTokenCollection(request) {
-        return this.tokenDomainService.getTokenCollection({
+        const collection = await this.tokenDomainService.getTokenCollection({
             accountAddress: request.accountAddress || '',
             contractAddress: request.contractAddress,
             abi: request.abi,
@@ -45393,6 +47321,7 @@ class Web3ApplicationService {
             maxTokens: request.maxTokens,
             tokenIds: request.tokenIds
         });
+        return localizeTokenCollection(collection, this.getLocale());
     }
     /**
      * Resolve IPFS URLs to HTTPS if needed.
@@ -45400,7 +47329,7 @@ class Web3ApplicationService {
      * IPFS gateway is resolved from tenant configuration (chain-agnostic).
      */
     async resolveIPFSUrl(url) {
-        return this.metadataDomainService.resolveIPFSUrl(url);
+        return this.ipfsApi.resolveIPFSUrl(url);
     }
     /**
      * Get IPFS gateway domain from tenant configuration.
@@ -45409,7 +47338,7 @@ class Web3ApplicationService {
      * @returns Gateway domain (e.g., 'pers.mypinata.cloud')
      */
     async getIpfsGatewayDomain() {
-        return this.metadataDomainService.getIpfsGatewayDomain();
+        return this.ipfsApi.getIpfsGatewayDomain();
     }
     /**
      * Fetch and process metadata from any URI with IPFS conversion.
@@ -45419,7 +47348,8 @@ class Web3ApplicationService {
      * IPFS gateway is resolved from tenant configuration (chain-agnostic).
      */
     async fetchAndProcessMetadata(tokenUri) {
-        return this.metadataDomainService.fetchAndProcessMetadata(tokenUri);
+        const metadata = await this.ipfsApi.fetchAndProcessMetadata(tokenUri);
+        return metadata ? localizeTokenMetadata(metadata, this.getLocale()) : null;
     }
 }
 
@@ -45496,109 +47426,37 @@ class Web3InfrastructureApi {
 }
 
 /**
- * IPFSInfrastructureApi - Infrastructure implementation for IPFS operations
- * Uses TenantManager for IPFS gateway resolution with centralized caching
- *
- * IMPORTANT: IPFS gateway domain is now fetched from tenant configuration (TenantClientConfigDTO),
- * not from chain data. This is the correct architecture since IPFS is chain-agnostic.
+ * IPFSInfrastructureApi - Web3-side adapter over the shared IPFS and token metadata resolvers.
+ * Pass the SDK's shared `sources` to reuse its resolvers; otherwise they are built from `config`.
+ * Results are raw (language-agnostic); the locale is applied where data is handed out.
  */
 class IPFSInfrastructureApi {
-    constructor(tenantManager) {
-        this.tenantManager = tenantManager;
-        this.cache = globalCacheService.createNamespace('ipfs');
+    constructor(config, sources = createIpfsSources(config)) {
+        this.resolver = sources.resolver;
+        this.metadata = sources.metadata;
     }
-    /**
-     * Get IPFS gateway domain from tenant configuration.
-     *
-     * @returns The IPFS gateway domain from tenant configuration
-     * @throws Error if tenant config is not found or ipfsGatewayDomain is not configured
-     */
-    async getIpfsGatewayDomain() {
-        const cacheKey = 'gateway';
-        return this.cache.getOrSet(cacheKey, async () => {
-            const clientConfig = await this.tenantManager.getClientConfig();
-            if (!clientConfig.ipfsGatewayDomain) {
-                throw new Error(`IPFS gateway domain not configured for tenant. ` +
-                    `Please configure ipfsGatewayDomain in the tenant configuration.`);
-            }
-            return clientConfig.ipfsGatewayDomain;
-        }, CacheTTL.GATEWAY);
+    getIpfsGatewayDomain() {
+        return this.resolver.getGatewayDomain();
     }
-    /**
-     * Resolve IPFS URL to HTTPS URL using tenant's configured gateway.
-     *
-     * @param url - The URL to resolve (can be ipfs:// or https://)
-     * @returns Resolved HTTPS URL
-     */
-    async resolveIPFSUrl(url) {
-        if (url.startsWith('ipfs://')) {
-            const gateway = await this.getIpfsGatewayDomain();
-            return url.replace('ipfs://', `https://${gateway}/ipfs/`);
-        }
-        return url;
+    resolveIPFSUrl(url) {
+        return this.resolver.resolveUrl(url);
     }
-    /**
-     * Fetch metadata from tokenURI, resolve all IPFS URLs, and normalize to SDK format.
-     *
-     * NORMALIZATION BOUNDARY: This is the single place where ERC metadata standard
-     * (snake_case: image, animation_url) is converted to SDK format (camelCase: imageUrl, animationUrl).
-     * All downstream consumers receive normalized SDK format with resolved HTTPS URLs.
-     *
-     * @param tokenUri - Token URI (can be ipfs:// or https://)
-     * @returns Normalized TokenMetadata with resolved HTTPS URLs, or null on error
-     */
-    async fetchAndProcessMetadata(tokenUri) {
-        try {
-            const resolvedUri = await this.resolveIPFSUrl(tokenUri);
-            const response = await fetch(resolvedUri);
-            if (!response.ok) {
-                throw new Error(`HTTP error! status: ${response.status}`);
-            }
-            const rawMetadata = await response.json();
-            // Resolve any IPFS URLs in string fields
-            for (const key of Object.keys(rawMetadata)) {
-                const value = rawMetadata[key];
-                if (typeof value === 'string' && value.startsWith('ipfs://')) {
-                    rawMetadata[key] = await this.resolveIPFSUrl(value);
-                }
-            }
-            // Extract custom properties (anything not in ERC standard)
-            const customProperties = Object.fromEntries(Object.entries(rawMetadata).filter(([key]) => !['name', 'description', 'image', 'animation_url', 'external_url', 'attributes'].includes(key)));
-            // Return normalized SDK format
-            const result = {
-                name: String(rawMetadata.name ?? ''),
-                description: String(rawMetadata.description ?? ''),
-                imageUrl: String(rawMetadata.image ?? ''),
-                animationUrl: rawMetadata.animation_url ? String(rawMetadata.animation_url) : undefined,
-                externalUrl: rawMetadata.external_url ? String(rawMetadata.external_url) : undefined,
-                attributes: Array.isArray(rawMetadata.attributes) ? rawMetadata.attributes : [],
-                ...customProperties
-            };
-            return result;
-        }
-        catch (error) {
-            console.error('Error fetching metadata:', error);
-            return null;
-        }
+    fetchAndProcessMetadata(tokenUri) {
+        return this.metadata.fetch(tokenUri);
     }
     async fetchFromUrl(url) {
         try {
-            const response = await fetch(url);
-            if (!response.ok) {
-                throw new Error(`Failed to fetch from ${url}: ${response.statusText}`);
-            }
-            return await response.json();
+            return await this.resolver.fetchJson(url);
         }
         catch (error) {
             console.error(`Error fetching from URL ${url}:`, error);
             throw error;
         }
     }
-    /**
-     * Clear IPFS cache for this service
-     */
+    /** Clear cached gateway and metadata entries */
     clearCache() {
-        this.cache.clear();
+        this.resolver.clearCache();
+        this.metadata.clearCache();
     }
 }
 
@@ -45715,12 +47573,11 @@ class Web3Manager {
         this.web3ChainService = new Web3ChainService(web3ChainApi);
         // Initialize Web3 Application service with TenantManager for IPFS
         const web3InfrastructureApi = new Web3InfrastructureApi(this.web3ChainService);
-        const ipfsInfrastructureApi = new IPFSInfrastructureApi(this.tenantManager);
-        this.web3ApplicationService = new Web3ApplicationService(web3InfrastructureApi, ipfsInfrastructureApi);
+        const ipfsInfrastructureApi = new IPFSInfrastructureApi(this.tenantManager, this.tenantManager.ipfs.sources);
+        this.web3ApplicationService = new Web3ApplicationService(web3InfrastructureApi, ipfsInfrastructureApi, () => apiClient.getLocale());
         // Initialize domain services for managers
         const contractDomainService = new ContractDomainService();
-        const metadataDomainService = new MetadataDomainService(ipfsInfrastructureApi);
-        this.tokenDomainService = new TokenDomainService(web3InfrastructureApi, metadataDomainService, contractDomainService);
+        this.tokenDomainService = new TokenDomainService(web3InfrastructureApi, ipfsInfrastructureApi, contractDomainService);
     }
     /**
      * Get the TokenCollectionManager for NFT collection operations.
@@ -45748,7 +47605,7 @@ class Web3Manager {
      */
     get collectionManager() {
         if (!this._collectionManager) {
-            this._collectionManager = new TokenCollectionManager(this.tokenDomainService, this.eventEmitter);
+            this._collectionManager = new TokenCollectionManager(this.tokenDomainService, this.eventEmitter, { getLocale: () => this.apiClient.getLocale() });
         }
         return this._collectionManager;
     }
@@ -45819,10 +47676,10 @@ class Web3Manager {
      *
      * @param tokenUri - Token URI to fetch metadata from
      * @returns Promise resolving to processed metadata or null if not found
-     * @deprecated Use sdk.tenants.fetchAndProcessMetadata() instead - IPFS is chain-agnostic
+     * @deprecated Use sdk.ipfs.fetchMetadata() instead - IPFS is chain-agnostic
      */
     async fetchAndProcessMetadata(tokenUri) {
-        return this.tenantManager.fetchAndProcessMetadata(tokenUri);
+        return this.web3ApplicationService.fetchAndProcessMetadata(tokenUri);
     }
     /**
      * Get blockchain chain data by chain ID
@@ -46145,7 +48002,7 @@ const useWeb3 = () => {
      * Converts an ipfs:// URL to an HTTPS URL using the tenant's configured IPFS gateway.
      * Non-IPFS URLs are returned unchanged.
      *
-     * Note: Uses sdk.tenants for IPFS resolution (chain-agnostic).
+     * Note: Uses sdk.ipfs for IPFS resolution (chain-agnostic).
      *
      * @param url - IPFS URL to resolve (ipfs://...)
      * @returns Promise resolving to HTTP gateway URL
@@ -46162,7 +48019,7 @@ const useWeb3 = () => {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.tenants.resolveIpfsUrl(url);
+            const result = await sdk.ipfs.resolveUrl(url);
             return result;
         }
         catch (error) {
@@ -46173,7 +48030,7 @@ const useWeb3 = () => {
     /**
      * Fetch and process token metadata from a URI
      *
-     * Note: Uses sdk.tenants for metadata fetching (chain-agnostic IPFS).
+     * Note: Uses sdk.ipfs for metadata fetching (chain-agnostic IPFS).
      *
      * @param tokenUri - Token URI to fetch metadata from
      * @returns Promise resolving to processed metadata or null
@@ -46183,7 +48040,7 @@ const useWeb3 = () => {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.tenants.fetchAndProcessMetadata(tokenUri);
+            const result = await sdk.ipfs.fetchMetadata(tokenUri);
             return result;
         }
         catch (error) {
@@ -46810,7 +48667,7 @@ class AngularHttpClientAdapter {
     }
     async convertObservableToPromise(observable) {
         // Dynamically import firstValueFrom to avoid build-time dependency
-        const { firstValueFrom } = await Promise.resolve().then(function () { return require('./index-CzLxqePZ.js'); }).then(function (n) { return n.index; });
+        const { firstValueFrom } = await import('rxjs');
         return firstValueFrom(observable);
     }
     mergeOptions(options) {
@@ -46876,7 +48733,10 @@ class BrowserFetchClientAdapter {
         }
         const response = await fetch(url, fetchOptions);
         if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            const httpError = new Error(`HTTP ${response.status}: ${response.statusText}`);
+            httpError.status = response.status;
+            httpError.statusText = response.statusText;
+            throw httpError;
         }
         // Handle different response types
         const contentType = response.headers.get('content-type');
@@ -48219,12 +50079,12 @@ const useBusiness = () => {
      * console.log('Business created:', business);
      * ```
      */
-    const createBusiness = react.useCallback(async (displayName) => {
+    const createBusiness = react.useCallback(async (dto) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.businesses.createBusiness(displayName);
+            const result = await sdk.businesses.createBusiness(dto);
             return result;
         }
         catch (error) {
@@ -49083,7 +50943,7 @@ const useRedemptions = () => {
  * Automatically handles IPFS URLs by resolving them to HTTPS via tenant's gateway.
  * Non-IPFS URLs are returned as-is. Handles loading and error states.
  *
- * Uses sdk.tenants for IPFS resolution (lightweight, no Web3 deps).
+ * Uses sdk.ipfs for IPFS resolution (lightweight, no Web3 deps).
  *
  * @param url - The URL to resolve (can be ipfs://, https://, or undefined)
  * @returns Object with resolved URL, loading state, and error
@@ -49115,7 +50975,7 @@ function useResolvedUrl(url) {
         }
         setIsLoading(true);
         setError(null);
-        sdk.tenants.resolveIpfsUrl(url)
+        sdk.ipfs.resolveUrl(url)
             .then((resolved) => {
             setResolvedUrl(resolved);
         })
@@ -49142,7 +51002,7 @@ function useResolvedUrl(url) {
  * Handles IPFS resolution automatically and returns parsed metadata
  * with all nested IPFS URLs already resolved to HTTPS.
  *
- * Uses sdk.tenants for metadata fetching (lightweight, no Web3 deps).
+ * Uses sdk.ipfs for metadata fetching (lightweight, no Web3 deps).
  *
  * @param metadataUri - The metadata URI to fetch (can be ipfs:// or https://)
  * @returns Object with metadata, loading state, error, and refresh function
@@ -49167,7 +51027,7 @@ function useResolvedUrl(url) {
  * ```
  */
 function useMetadata(metadataUri) {
-    const { sdk, isInitialized } = usePersSDK();
+    const { sdk, isInitialized, locale } = usePersSDK();
     const [metadata, setMetadata] = react.useState(null);
     const [isLoading, setIsLoading] = react.useState(false);
     const [error, setError] = react.useState(null);
@@ -49179,7 +51039,7 @@ function useMetadata(metadataUri) {
         setIsLoading(true);
         setError(null);
         try {
-            const result = await sdk.tenants.fetchAndProcessMetadata(metadataUri);
+            const result = await sdk.ipfs.fetchMetadata(metadataUri);
             setMetadata(result);
         }
         catch (err) {
@@ -49189,12 +51049,12 @@ function useMetadata(metadataUri) {
         finally {
             setIsLoading(false);
         }
-    }, [metadataUri, isInitialized, sdk]);
+    }, [metadataUri, isInitialized, sdk, locale]);
     react.useEffect(() => {
         fetchMetadata();
     }, [fetchMetadata]);
     return {
-        /** Parsed metadata with resolved IPFS URLs (imageUrl, animationUrl, etc.) */
+        /** Parsed metadata with resolved IPFS URLs (imageUrl, animationUrl, etc.), localized for the current locale */
         metadata,
         /** Whether fetch is in progress */
         isLoading,
@@ -50823,6 +52683,8 @@ exports.AuthManager = AuthManager;
 exports.AuthService = AuthService;
 exports.AuthTokenManager = AuthTokenManager;
 exports.AuthenticationError = AuthenticationError;
+exports.BUSINESS_TRANSLATABLE_FIELDS = BUSINESS_TRANSLATABLE_FIELDS;
+exports.BUSINESS_TYPE_TRANSLATABLE_FIELDS = BUSINESS_TYPE_TRANSLATABLE_FIELDS;
 exports.BaseTokenService = BaseTokenService;
 exports.BookingApi = BookingApi;
 exports.BookingManager = BookingManager;
@@ -50833,6 +52695,11 @@ exports.BusinessManager = BusinessManager;
 exports.BusinessMembershipApi = BusinessMembershipApi;
 exports.BusinessMembershipService = BusinessMembershipService;
 exports.BusinessService = BusinessService;
+exports.CAMPAIGN_TRANSLATABLE_FIELDS = CAMPAIGN_TRANSLATABLE_FIELDS;
+exports.CAMPAIGN_TRIGGER_TRANSLATABLE_FIELDS = CAMPAIGN_TRIGGER_TRANSLATABLE_FIELDS;
+exports.CHAIN_READ_PERMISSIONS = CHAIN_READ_PERMISSIONS;
+exports.CHAIN_WRITE_PERMISSIONS = CHAIN_WRITE_PERMISSIONS;
+exports.CUSTOM_FIELD_TRANSLATABLE_FIELDS = CUSTOM_FIELD_TRANSLATABLE_FIELDS;
 exports.CacheService = CacheService;
 exports.CacheTTL = CacheTTL;
 exports.CampaignApi = CampaignApi;
@@ -50844,6 +52711,8 @@ exports.CommonErrorCodes = CommonErrorCodes;
 exports.CustomFieldDefinitionManager = CustomFieldDefinitionManager;
 exports.DATA_SOURCE_CHANNELS = DATA_SOURCE_CHANNELS;
 exports.DEFAULT_DATA_SOURCE = DEFAULT_DATA_SOURCE;
+exports.DEFAULT_PAGE = DEFAULT_PAGE;
+exports.DEFAULT_PAGE_SIZE = DEFAULT_PAGE_SIZE;
 exports.DEFAULT_PERS_CONFIG = DEFAULT_PERS_CONFIG;
 exports.DPOP_STORAGE_KEYS = DPOP_STORAGE_KEYS;
 exports.DPoPManager = DPoPManager;
@@ -50858,6 +52727,7 @@ exports.ENGAGEMENT_RATE_FORMULA = ENGAGEMENT_RATE_FORMULA;
 exports.EntityTypes = EntityTypes;
 exports.ErrorDomains = ErrorDomains;
 exports.ErrorUtils = ErrorUtils;
+exports.ExternalEventType = ExternalEventType;
 exports.FATAL_AUTH_CODES = FATAL_AUTH_CODES;
 exports.FileApi = FileApi;
 exports.FileManager = FileManager;
@@ -50871,16 +52741,24 @@ exports.IMAGE_CDN_MAX_INPUT_SIZE = IMAGE_CDN_MAX_INPUT_SIZE;
 exports.IMAGE_CDN_PRESETS = IMAGE_CDN_PRESETS;
 exports.IMAGE_CDN_SUPPORTED_FORMATS = IMAGE_CDN_SUPPORTED_FORMATS;
 exports.IndexedDBTokenStorage = IndexedDBTokenStorage;
+exports.IpfsManager = IpfsManager;
 exports.KNOWN_SOURCE_DOMAINS = KNOWN_SOURCE_DOMAINS;
+exports.LOCALE_HEADER = LOCALE_HEADER;
+exports.LOCALE_MAX_LENGTH = LOCALE_MAX_LENGTH;
 exports.LOCATION_TYPES = LOCATION_TYPES;
 exports.LocalStorageTokenStorage = LocalStorageTokenStorage;
+exports.LocaleManager = LocaleManager;
 exports.LogoutRequired = LogoutRequired;
 exports.MEMBERSHIP_ROLE_HIERARCHY = MEMBERSHIP_ROLE_HIERARCHY;
 exports.MemoryTokenStorage = MemoryTokenStorage;
 exports.NativeTokenTypes = NativeTokenTypes;
 exports.NetworkError = NetworkError;
 exports.NodeHttpClientAdapter = NodeHttpClientAdapter;
+exports.NotificationApi = NotificationApi;
+exports.NotificationManager = NotificationManager;
+exports.NotificationService = NotificationService;
 exports.OttAuthMethod = OttAuthMethod;
+exports.PURCHASE_TOKEN_TRANSLATABLE_FIELDS = PURCHASE_TOKEN_TRANSLATABLE_FIELDS;
 exports.PaymentApi = PurchaseApi;
 exports.PaymentService = PaymentService;
 exports.PersApiClient = PersApiClient;
@@ -50892,12 +52770,18 @@ exports.PersSDKProvider = PersSDKProvider;
 exports.ProviderTokenRefreshNeeded = ProviderTokenRefreshNeeded;
 exports.PurchaseManager = PurchaseManager;
 exports.QUERY_OPERATOR_SQL_MAP = QUERY_OPERATOR_SQL_MAP;
+exports.REDEMPTION_ELIGIBILITY_GATES = REDEMPTION_ELIGIBILITY_GATES;
+exports.REDEMPTION_TRANSLATABLE_FIELDS = REDEMPTION_TRANSLATABLE_FIELDS;
+exports.REDEMPTION_TYPE_TRANSLATABLE_FIELDS = REDEMPTION_TYPE_TRANSLATABLE_FIELDS;
 exports.ReactNativeDPoPProvider = ReactNativeDPoPProvider;
 exports.ReactNativeHttpClient = ReactNativeHttpClient;
 exports.ReactNativeSecureStorage = ReactNativeSecureStorage;
 exports.RedemptionApi = RedemptionApi;
 exports.RedemptionManager = RedemptionManager;
 exports.RedemptionService = RedemptionService;
+exports.RedirectApi = RedirectApi;
+exports.RedirectManager = RedirectManager;
+exports.RedirectService = RedirectService;
 exports.SDK_NAME = SDK_NAME;
 exports.SDK_USER_AGENT = SDK_USER_AGENT;
 exports.SDK_VERSION = SDK_VERSION;
@@ -50906,9 +52790,16 @@ exports.SOURCE_LOGIC_TYPES = SOURCE_LOGIC_TYPES;
 exports.SOURCE_LOGIC_TYPE_VALUES = SOURCE_LOGIC_TYPE_VALUES;
 exports.SdkErrorCodes = SdkErrorCodes;
 exports.StaticJwtAuthProvider = StaticJwtAuthProvider;
+exports.TENANT_TRANSLATABLE_FIELDS = TENANT_TRANSLATABLE_FIELDS;
+exports.TOKEN_METADATA_TRANSLATABLE_FIELDS = TOKEN_METADATA_TRANSLATABLE_FIELDS;
 exports.TOKEN_VALIDITY_TYPE_VALUES = TOKEN_VALIDITY_TYPE_VALUES;
 exports.TRANSACTION_FORMATS = TRANSACTION_FORMATS;
 exports.TRANSACTION_FORMAT_DESCRIPTIONS = TRANSACTION_FORMAT_DESCRIPTIONS;
+exports.TRANSLATIONS_MAX_LOCALES = TRANSLATIONS_MAX_LOCALES;
+exports.TRANSLATIONS_MAX_SIZE = TRANSLATIONS_MAX_SIZE;
+exports.TRANSLATION_FIELD_MAX_LENGTH = TRANSLATION_FIELD_MAX_LENGTH;
+exports.TRANSLATION_VALUE_MAX_LENGTH = TRANSLATION_VALUE_MAX_LENGTH;
+exports.TRIGGER_SOURCE_TRANSLATABLE_FIELDS = TRIGGER_SOURCE_TRANSLATABLE_FIELDS;
 exports.TRIGGER_SOURCE_TYPES = TRIGGER_SOURCE_TYPES;
 exports.TRIGGER_SOURCE_TYPE_VALUES = TRIGGER_SOURCE_TYPE_VALUES;
 exports.TenantApi = TenantApi;
@@ -50928,6 +52819,7 @@ exports.TriggerSourceApi = TriggerSourceApi;
 exports.TriggerSourceManager = TriggerSourceManager;
 exports.TriggerSourceService = TriggerSourceService;
 exports.URL_REGEX = URL_REGEX;
+exports.USER_STATUS_TYPE_TRANSLATABLE_FIELDS = USER_STATUS_TYPE_TRANSLATABLE_FIELDS;
 exports.UUID_REGEX = UUID_REGEX;
 exports.UserApi = UserApi;
 exports.UserManager = UserManager;
@@ -50936,6 +52828,7 @@ exports.UserStatusApi = UserStatusApi;
 exports.UserStatusManager = UserStatusManager;
 exports.UserStatusService = UserStatusService;
 exports.VALID_BUSINESS_MEMBERSHIP_RELATIONS = VALID_BUSINESS_MEMBERSHIP_RELATIONS;
+exports.VALID_BUSINESS_RELATIONS = VALID_BUSINESS_RELATIONS;
 exports.VALID_CAMPAIGN_CLAIM_RELATIONS = VALID_CAMPAIGN_CLAIM_RELATIONS;
 exports.VALID_CAMPAIGN_RELATIONS = VALID_CAMPAIGN_RELATIONS;
 exports.VALID_REDEMPTION_REDEEM_RELATIONS = VALID_REDEMPTION_REDEEM_RELATIONS;
@@ -50951,6 +52844,7 @@ exports.WebhookApi = WebhookApi;
 exports.WebhookManager = WebhookManager;
 exports.WebhookService = WebhookService;
 exports.apiPublicKeyTestPrefix = apiPublicKeyTestPrefix;
+exports.assertAvailable = assertAvailable;
 exports.buildApiRoot = buildApiRoot;
 exports.buildBurnRequest = buildBurnRequest;
 exports.buildImageCdnUrl = buildImageCdnUrl;
@@ -50962,9 +52856,12 @@ exports.buildPaginationParams = buildPaginationParams;
 exports.buildPendingTransactionData = buildPendingTransactionData;
 exports.buildSubmissionRequest = buildSubmissionRequest;
 exports.buildTransferRequest = buildTransferRequest;
+exports.buildTranslationsPatch = buildTranslationsPatch;
 exports.buildWalletEventsWsUrl = buildWalletEventsWsUrl;
 exports.builtInUserFieldMetadata = builtInUserFieldMetadata;
 exports.builtInUserFields = builtInUserFields;
+exports.canManageCampaignTriggerSources = canManageCampaignTriggerSources;
+exports.cleanTranslations = cleanTranslations;
 exports.compareValues = compareValues;
 exports.computeBookingStatus = computeBookingStatus;
 exports.createPersEventsClient = createPersEventsClient;
@@ -50974,18 +52871,21 @@ exports.createUserIdentifierObject = createUserIdentifierObject;
 exports.createUserStatusSDK = createUserStatusSDK;
 exports.customFieldEntityTypes = customFieldEntityTypes;
 exports.detectChannelFromUserAgent = detectChannelFromUserAgent;
+exports.detectDeviceLocale = detectDeviceLocale;
 exports.detectEnvironment = detectEnvironment;
 exports.detectIdentifierType = detectIdentifierType;
 exports.detectReactNativePlatform = detectReactNativePlatform;
 exports.detectSourceFromReferrer = detectSourceFromReferrer;
 exports.detectWebPlatform = detectWebPlatform;
 exports.environment = environment;
+exports.evaluateRedemptionEligibility = evaluateRedemptionEligibility;
 exports.extractData = extractData;
 exports.extractDeadlineFromSigningData = extractDeadlineFromSigningData;
 exports.extractIpfsCid = extractIpfsCid;
 exports.extractPagination = extractPagination;
 exports.fetchAllPages = fetchAllPages;
 exports.getAllBuiltInFieldDefinitions = getAllBuiltInFieldDefinitions;
+exports.getAvailabilityStatus = getAvailabilityStatus;
 exports.getBuiltInFieldDefinition = getBuiltInFieldDefinition;
 exports.getMetadataFromTokenUnitResponse = getMetadataFromTokenUnitResponse;
 exports.getOperatorText = getOperatorText;
@@ -50994,6 +52894,7 @@ exports.getSelectOptionsLabelDefault = getSelectOptionsLabelDefault;
 exports.getSigningUrl = getSigningUrl;
 exports.globalCacheService = globalCacheService;
 exports.hasMinimumRole = hasMinimumRole;
+exports.inheritTranslations = inheritTranslations;
 exports.initializeReactNativePolyfills = initializeReactNativePolyfills;
 exports.isBookingStatusValid = isBookingStatusValid;
 exports.isBuiltInUserField = isBuiltInUserField;
@@ -51003,6 +52904,8 @@ exports.isErrorMessage = isErrorMessage;
 exports.isEventMessage = isEventMessage;
 exports.isFatalAuthErrorInMessage = isFatalAuthErrorInMessage;
 exports.isIpfsUrl = isIpfsUrl;
+exports.isNftTokenType = isNftTokenType;
+exports.isNotificationPendingMessage = isNotificationPendingMessage;
 exports.isPaginatedResponse = isPaginatedResponse;
 exports.isPingMessage = isPingMessage;
 exports.isServerMessage = isServerMessage;
@@ -51012,6 +52915,7 @@ exports.isUUID = isUUID;
 exports.isUnsubscribedMessage = isUnsubscribedMessage;
 exports.isUserIdentifierObject = isUserIdentifierObject;
 exports.isValidBusinessMembershipRelation = isValidBusinessMembershipRelation;
+exports.isValidBusinessRelation = isValidBusinessRelation;
 exports.isValidCampaignClaimRelation = isValidCampaignClaimRelation;
 exports.isValidCampaignRelation = isValidCampaignRelation;
 exports.isValidEmail = isValidEmail;
@@ -51026,16 +52930,23 @@ exports.isValidUrl = isValidUrl;
 exports.isValidUserRelation = isValidUserRelation;
 exports.isValidUuid = isValidUuid;
 exports.isValidWalletAddress = isValidWalletAddress;
+exports.localizeFields = localizeFields;
+exports.meetsMinimumStatusRequirement = meetsMinimumStatusRequirement;
+exports.mergeTranslations = mergeTranslations;
 exports.mergeWithDefaults = mergeWithDefaults;
 exports.needsExternalSigning = needsExternalSigning;
 exports.needsSubmission = needsSubmission;
 exports.normalizeFilters = normalizeFilters;
+exports.normalizeLocale = normalizeLocale;
 exports.normalizeToPaginated = normalizeToPaginated;
 exports.operatorText = operatorText;
 exports.parseUserAgentForPlatform = parseUserAgentForPlatform;
 exports.parseUtmParams = parseUtmParams;
+exports.pickTranslationFields = pickTranslationFields;
 exports.registerIdentifierType = registerIdentifierType;
+exports.resolveTranslation = resolveTranslation;
 exports.selectOptionsSourceEntities = selectOptionsSourceEntities;
+exports.setIncludeParam = setIncludeParam;
 exports.testnetPrefix = testnetPrefix;
 exports.testnetShortPrefix = testnetShortPrefix;
 exports.uniqueUserIdentifierKeys = uniqueUserIdentifierKeys;
@@ -51067,5 +52978,7 @@ exports.userModelFields = userModelFields;
 exports.validateAllFields = validateAllFields;
 exports.validateFieldComparisons = validateFieldComparisons;
 exports.validateFieldValue = validateFieldValue;
+exports.validateTranslationsLimits = validateTranslationsLimits;
+exports.validateTranslationsPatch = validateTranslationsPatch;
 exports.warnIfProblematicEnvironment = warnIfProblematicEnvironment;
 //# sourceMappingURL=index.js.map