[joaodordio]

📝 Summary

Adds autoUserUpdate (true | 'oncePerUser' | false, default true) to control the users/update call made by setUserID and JWT setEmail.

🎟️ Jira Ticket: SDK-128

📖 Description

setUserID (both modes) and JWT setEmail call tryUser, which sends POST /api/users/update with up to 3 retries. A customer whose site does a full reload on every navigation identifies the user on every page load, so they send one users/update per page view. That call also takes a token from the org's volume rate-limit bucket, which is shared with updateSubscriptions and lists/subscribe.

This PR:

• Adds autoUserUpdate to Options, defaulting to true. Anything other than false or 'oncePerUser' behaves like true, so nothing changes for customers who don't set it.
• 'oncePerUser': after a successful users/update, stores email:<email> or userID:<id> in localStorage (itbl_user_updated), and skips the call while the same identity is identified again. A different identity sends it again. logout clears the stored identity. A failed call stores nothing, so the next identify retries.
• false: never sends the call. The customer creates the profile with the already-public updateUser, or from their server.
• Puts the logic in a small src/authorization/autoUserUpdate.ts; authorization.ts only changes at the three tryUser call sites and both logout methods.
• README: documents the option, and fixes the updateUser endpoint name and the WithJWT setEmail/setUserID signatures.

Backend context, checked on Iterable origin/master:

• In userId-based and hybrid projects, in-app and embedded message requests return 400 for a user with no profile. That's why 'oncePerUser' exists: plain false would break those requests for first-time users unless the customer creates the profile.
• users/merge with a missing destination renames the source profile instead of failing, so merging an unknown user still works when the call is skipped.

Mobile parity: Android and iOS don't call users/update on login and skip a repeat login with the same identity. 'oncePerUser' brings Web close to that, and the name follows autoPushRegistration.

Known limitation: the stored identity isn't scoped by API key. A site that uses two Iterable projects on the same origin with 'oncePerUser' would skip profile creation in the second one.

🧪 How to test?

1. yarn jest --config jest.config.js src/authorization/authorization.autoUserUpdate.test.ts. It covers true, false, 'oncePerUser', unrecognized values, logout, failed calls, and email/userId collisions across non-JWT setUserID, JWT setUserID and JWT setEmail.
2. Full suite: yarn jest --config jest.config.js (27 suites, 419 tests passing) and yarn typecheck.
3. Sample app: initializeWithConfig({ configOptions: { autoUserUpdate: 'oncePerUser' }, ... }), call setUserID('u1'), reload, and call it again. Only the first identify sends /users/update. After logout(), the next identify sends it again.

🧾 Changelog

CHANGELOG Unreleased entry added (SDK-128).

📹 Loom recording if applicable

N/A

🐞 Github Issues solved

N/A

📚 Docs PR if applicable

https://github.com/Iterable/iterable-docs/pull/1614

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.57%. Comparing base (86094c5) to head (857c2ed).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #591      +/-   ##
==========================================
+ Coverage   75.32%   75.57%   +0.24%     
==========================================
  Files          57       58       +1     
  Lines        2752     2776      +24     
  Branches      806      810       +4     
==========================================
+ Hits         2073     2098      +25     
+ Misses        678      677       -1     
  Partials        1        1              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.