agumail-js 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -61,7 +61,7 @@ function toAguMailError(cause) {
 }
 
 // src/runtime.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var BROWSER_MESSAGE = "agumail-js runs on your server only. Your AguMail API key is secret, and code in a browser hands it to every visitor. Call AguMail from an API route, a server action or your backend instead.";
 var API_KEY_ENV = "AGUMAIL_API_KEY";
 var MAX_DELAY_MS = 2147483647;
@@ -122,6 +122,7 @@ var UNIQUE_ID_MAX = 120;
 var EVENT_PROPERTIES_MAX = 30;
 var EVENT_PROPERTIES_CHARS = 8e3;
 var STATUS_EMAIL_MAX = 320;
+var USER_ID_MAX = 200;
 var SIGNUP_EMAIL_MAX = 254;
 var FORM_ID_MAX = 100;
 var FORM_NAME_MAX = 200;
@@ -132,8 +133,8 @@ var EMAIL = /^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z
 var SIGNUP_EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 var BUILDER = /^[a-z0-9][a-z0-9_-]{0,39}$/;
 var PROFILE_FIELDS = ["firstName", "lastName", "phone", "timezone", "tags", "properties", "customerSince"];
-var CONTACT_FIELDS = ["email", "subscribed", ...PROFILE_FIELDS];
-var EVENT_FIELDS = ["email", "event", "properties", "value", "occurredAt", "uniqueId", "contact"];
+var CONTACT_FIELDS = ["email", "userId", "subscribed", ...PROFILE_FIELDS];
+var EVENT_FIELDS = ["email", "userId", "event", "properties", "value", "occurredAt", "uniqueId", "contact"];
 var SIGNUP_FIELDS = [
   "email",
   "doubleOptIn",
@@ -150,8 +151,12 @@ var SIGNUP_FIELDS = [
 var FORM_FIELDS = ["id", "name", "builder"];
 var CONTACT_HINTS = {
   name: "Use firstName and lastName.",
-  customFields: "Use properties.",
-  userId: "AguMail identifies contacts by email for now."
+  customFields: "Use properties."
+};
+var PROFILE_HINTS = {
+  ...CONTACT_HINTS,
+  email: "Put it on the event itself.",
+  userId: "Put it on the event itself."
 };
 var EVENT_HINTS = {
   metric: "Use event.",
@@ -167,20 +172,27 @@ function contactRecord(input, at) {
     throw invalidInput(`${at}.subscribed must be true or false.`);
   }
   return {
-    email: email(c.email, `${at}.email`),
+    ...identity(c, at),
     ...profileFields(c, at),
     consent: { optedIn: c.subscribed !== false, source: "api" }
   };
 }
-function profileRecord(address, input, at) {
+function profileRecord(who, input, at) {
   const c = object(input, at);
-  knownKeys(c, PROFILE_FIELDS, at, CONTACT_HINTS, "Put your own fields in properties.");
-  return { email: address, ...profileFields(c, at) };
+  knownKeys(c, PROFILE_FIELDS, at, PROFILE_HINTS, "Put your own fields in properties.");
+  return { ...who, ...profileFields(c, at) };
 }
 function consentRecord(address, at, change) {
   const checked = email(address, at);
   return change === "subscribe" ? { email: checked, consent: { optedIn: true, source: "my_account" } } : { email: checked, unsubscribed: true, consentSource: "my_account" };
 }
+function identity(r, at) {
+  const out = {};
+  if (r.email !== void 0 && r.email !== null) out.email = email(r.email, `${at}.email`);
+  set(out, "userId", userId(r.userId, `${at}.userId`));
+  if (out.email === void 0 && out.userId === void 0) throw invalidInput(`${at}.email is required when there is no userId.`);
+  return out;
+}
 function profileFields(c, at) {
   const out = {};
   set(out, "firstName", text(c.firstName, `${at}.firstName`, NAME_MAX));
@@ -236,7 +248,7 @@ function fieldText(value, at) {
 function eventRecord(input, at) {
   const e = object(input, at);
   knownKeys(e, EVENT_FIELDS, at, EVENT_HINTS);
-  const address = email(e.email, `${at}.email`);
+  const who = identity(e, at);
   const metric = requiredText(e.event, `${at}.event`, METRIC_MAX).trim();
   if (!/[A-Za-z0-9]/.test(metric)) {
     throw invalidInput(
@@ -244,7 +256,7 @@ function eventRecord(input, at) {
     );
   }
   const uniqueId = e.uniqueId === void 0 || e.uniqueId === null ? randomId() : requiredText(e.uniqueId, `${at}.uniqueId`, UNIQUE_ID_MAX);
-  const record = { email: address, metric, uniqueId };
+  const record = { ...who, metric, uniqueId };
   set(record, "occurredAt", date(e.occurredAt, `${at}.occurredAt`));
   if (e.value !== void 0 && e.value !== null) {
     if (typeof e.value !== "number" || !Number.isFinite(e.value)) {
@@ -255,7 +267,7 @@ function eventRecord(input, at) {
   set(record, "properties", eventProperties(e.properties, `${at}.properties`));
   const checked = { record, uniqueId };
   if (e.contact !== void 0 && e.contact !== null) {
-    checked.contact = profileRecord(address, e.contact, `${at}.contact`);
+    checked.contact = profileRecord(who, e.contact, `${at}.contact`);
   }
   return checked;
 }
@@ -323,6 +335,11 @@ function statusEmail(value, at) {
   }
   return value;
 }
+function statusUserId(value, at) {
+  const id = idText(value, at);
+  if (id.length > USER_ID_MAX) throw invalidInput(`${at} can be at most ${USER_ID_MAX} characters (this one has ${id.length}).`);
+  return id;
+}
 function list(value, at) {
   if (!Array.isArray(value)) throw invalidInput(`${at} must be an array (got ${describe(value)}).`);
   return value;
@@ -333,6 +350,21 @@ function email(value, at) {
   if (!EMAIL.test(trimmed)) throw invalidInput(`${at} is not an email address AguMail accepts: "${value}".`);
   return trimmed;
 }
+function userId(value, at) {
+  if (value === void 0 || value === null) return void 0;
+  const id = idText(value, at);
+  if (id.trim() === "") throw invalidInput(`${at} cannot be blank.`);
+  if (id.length > USER_ID_MAX) throw invalidInput(`${at} can be at most ${USER_ID_MAX} characters (this one has ${id.length}).`);
+  return id;
+}
+function idText(value, at) {
+  if (typeof value === "string") return value;
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw invalidInput(`${at} must be text or a whole number (got ${describe(value)}).`);
+  }
+  if (!Number.isSafeInteger(value)) throw invalidInput(`${at} is too big to be exact as a number (got ${value}): send it as text.`);
+  return String(value);
+}
 function signupEmail(value, at) {
   if (typeof value !== "string") throw invalidInput(`${at} must be an email address (got ${describe(value)}).`);
   const trimmed = value.trim();
@@ -604,7 +636,14 @@ function messageOf(cause) {
 // src/client.ts
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
-var WARNING_CODES = ["unknown_contacts", "over_capacity", "signups_limited", "history"];
+var WARNING_CODES = [
+  "unknown_contacts",
+  "over_capacity",
+  "signups_limited",
+  "history",
+  "unknown_user_ids",
+  "conflicts"
+];
 var noThrow = Object.freeze({ throwOnError: false });
 var AguMail = class {
   contacts;
@@ -649,9 +688,12 @@ var AguMail = class {
   /**
    * Adds or updates a contact, and subscribes them unless you pass `subscribed: false`.
    * It never brings back someone who unsubscribed or bounced (`suppressedSkipped`).
+   * Pass your app's `userId` and AguMail knows them by it, so a changed email moves
+   * the same contact. A record that would mix two people up is refused without an
+   * error, and listed in `conflicted`.
    *
    * @example
-   * await agumail.identify({ email: 'sam@example.com', firstName: 'Sam' });
+   * await agumail.identify({ email: 'sam@example.com', userId: user.id, firstName: 'Sam' });
    */
   identify(contact, options) {
     const core = this.#core;
@@ -663,6 +705,7 @@ var AguMail = class {
   /**
    * identify for any number of contacts, 500 to a request. Every record is checked
    * first, and nothing is sent if one is wrong. Pass `backfill: true` for an import.
+   * Each entry of `conflicted` gives its contact's place in your array as `index`.
    *
    * @example
    * await agumail.identifyMany(users.map((u) => ({ email: u.email, subscribed: u.marketingOptIn })), { backfill: true });
@@ -675,8 +718,9 @@ var AguMail = class {
     });
   }
   /**
-   * Records something a contact did. AguMail skips events for people it doesn't have,
-   * so identify them first, or pass `contact` to upsert them (never subscribed) first.
+   * Records something a contact did, named by email or by your app's `userId`. AguMail
+   * skips events for people it doesn't have, so identify them first, or pass `contact`
+   * to upsert them (never subscribed) first.
    *
    * @example
    * await agumail.track({ email: 'sam@example.com', event: 'Created project', uniqueId: `project:${id}` });
@@ -691,7 +735,8 @@ var AguMail = class {
   }
   /**
    * track for any number of events, 500 to a request, each batch's contacts first.
-   * On failure, `error.uniqueIds` holds the id each event was sent with.
+   * On failure, `error.uniqueIds` holds the id each event was sent with. A conflict
+   * in `contacts.conflicted` gives its event's place in your array as `index`.
    *
    * @example
    * const { uniqueIds } = await agumail.trackMany(rows.map((r) => ({ email: r.email, event: 'Imported' })));
@@ -739,19 +784,23 @@ var AguMail = class {
   }
 };
 function contactsApi(core) {
-  const status = (emails, options) => core.run(options, async (call) => {
-    const one = typeof emails === "string";
-    const asked = one ? [statusEmail(emails, "email")] : list(emails, "emails").map((e, i) => statusEmail(e, `emails[${i}]`));
+  const lookup = (by, check) => (given, options) => core.run(options, async (call) => {
+    const key = `${by}s`;
+    const one = typeof given === "string" || by === "userId" && typeof given === "number";
+    const asked = one ? [check(given, by)] : list(given, key).map((v, i) => check(v, `${key}[${i}]`));
     const answers = [];
     for (let i = 0; i < asked.length; i += BATCH_SIZE) {
       const batch = asked.slice(i, i + BATCH_SIZE);
-      answers.push(...statuses(await core.post("/api/v1/contacts/status", { emails: batch }, batch.length, call)));
+      answers.push(...statuses(await core.post("/api/v1/contacts/status", { [key]: batch }, batch.length, call)));
     }
     if (!one) return answers;
-    return answers[0] ?? { email: asked[0], status: null, subscribed: false };
+    const first = asked[0];
+    const unknown = { email: by === "email" ? first : null, userId: by === "userId" ? first : null };
+    return answers[0] ?? { ...unknown, status: null, subscribed: false };
   });
   return {
-    status,
+    status: lookup("email", statusEmail),
+    statusByUserId: lookup("userId", statusUserId),
     subscribe: (emails, options) => core.run(options, (call) => core.consentChange(emails, "subscribe", call)),
     unsubscribe: (emails, options) => core.run(options, (call) => core.consentChange(emails, "unsubscribe", call))
   };
@@ -795,7 +844,7 @@ var Core = class {
   async run(options, work) {
     const given = options;
     const quiet = given?.throwOnError === false;
-    const call = { options: given, tally: emptyTally() };
+    const call = { options: given, tally: emptyTally(), conflicted: [] };
     try {
       if (this.#configProblem) throw invalidInput(this.#configProblem);
       const problem = callProblem(given);
@@ -808,7 +857,7 @@ var Core = class {
       this.#report(error);
       return { data: null, error };
     } finally {
-      this.#warn(call.tally);
+      this.#warn(call);
     }
   }
   post(path2, body, records, call) {
@@ -821,14 +870,19 @@ var Core = class {
     const { timeoutMs, signal } = call.options ?? {};
     return request(this.#transportNow(), { method: "GET", path: path2, records: 0, timeoutMs, signal });
   }
-  /** Sends records in batches, one after another, adding up what each batch reports. */
-  async countBatches(sender, records, extra, call) {
+  /**
+   * Sends records in batches, one after another, adding up what each batch reports.
+   * `indexOf` turns a record's place in `records` into its place in the caller's array.
+   */
+  async countBatches(sender, records, extra, call, indexOf = (i) => i) {
     let total;
     let sent = 0;
     for (const batch of batches(records, (r) => r)) {
       try {
-        const counts = sender.read(await this.post(sender.path, { [sender.key]: batch, ...extra }, batch.length, call));
-        sender.tally(call.tally, counts);
+        const offset = sent;
+        const body = await this.post(sender.path, { [sender.key]: batch, ...extra }, batch.length, call);
+        const counts = sender.read(body, (i) => indexOf(offset + i));
+        sender.tally(call, counts);
         total = total ? sender.add(total, counts) : counts;
         sent += batch.length;
       } catch (err) {
@@ -836,7 +890,7 @@ var Core = class {
         throw err;
       }
     }
-    return total ?? sender.read({});
+    return total ?? sender.read({}, indexOf);
   }
   /** Sends events in batches, upserting the contacts a batch carries just before it. */
   async sendEvents(checked, extra, call) {
@@ -846,8 +900,9 @@ var Core = class {
     try {
       for (const batch of batches(checked, (c) => c.record)) {
         const people = batch.flatMap((c) => c.contact ? [c.contact] : []);
+        const owners = batch.flatMap((c, i) => c.contact ? [sent + i] : []);
         if (people.length > 0) {
-          const landed = await this.countBatches(CONTACTS, people, extra, call);
+          const landed = await this.countBatches(CONTACTS, people, extra, call, (k) => owners[k] ?? k);
           contacts = contacts ? addContactCounts(contacts, landed) : landed;
         }
         const history = extra.backfill === true ? 0 : batch.filter((c) => isHistory(c.record)).length;
@@ -915,7 +970,7 @@ var Core = class {
   }
   async #flushQueued(options) {
     const result = { contacts: contactCounts({}), events: eventCounts({}), error: null };
-    const call = { options, tally: emptyTally() };
+    const call = { options, tally: emptyTally(), conflicted: [] };
     let events = [];
     let sending = "contacts";
     try {
@@ -938,7 +993,7 @@ var Core = class {
       result.error = error;
       this.#report(error);
     }
-    this.#warn(call.tally);
+    this.#warn(call);
     return result;
   }
   #transportNow() {
@@ -949,11 +1004,14 @@ var Core = class {
   #report(error) {
     callQuietly(this.#onError, error);
   }
-  #warn(tally) {
+  #warn(call) {
     if (this.#disabled || !this.#onWarning) return;
     for (const code of WARNING_CODES) {
-      const count2 = tally[code];
-      if (count2 > 0) callQuietly(this.#onWarning, { code, message: warningMessage(code, count2), count: count2 });
+      const count2 = call.tally[code];
+      if (count2 <= 0) continue;
+      const warning = { code, message: warningMessage(code, count2), count: count2 };
+      if (code === "conflicts") warning.conflicted = call.conflicted;
+      callQuietly(this.#onWarning, warning);
     }
   }
 };
@@ -978,15 +1036,25 @@ function warningMessage(code, n) {
       return `AguMail dropped ${n} ${many ? "signups" : "signup"} over its limit of 10 new addresses per visitor IP a minute. Pass the visitor's IP address as ip, not your server's.`;
     case "history":
       return `${n} ${many ? "events" : "event"} happened more than 72 hours ago, so AguMail stores ${them} as history and starts no flows from ${them}. Send events as they happen, or pass backfill: true for an import.`;
+    case "unknown_user_ids":
+      return `AguMail skipped ${n} ${many ? "contacts" : "contact"} sent with only a userId that no contact has. Send the email with the userId, so AguMail can add ${them}.`;
+    case "conflicts":
+      return `AguMail refused ${n} ${many ? "contacts" : "contact"} whose email belongs to someone else, so that two people are never mixed up: AguMail never merges contacts. warning.conflicted lists ${them}, and why.`;
   }
 }
 function emptyTally() {
-  return { unknown_contacts: 0, over_capacity: 0, signups_limited: 0, history: 0 };
+  return { unknown_contacts: 0, over_capacity: 0, signups_limited: 0, history: 0, unknown_user_ids: 0, conflicts: 0 };
 }
 function disabledAnswer(path2, body) {
   if (path2 !== "/api/v1/contacts/status") return {};
   const emails = body?.emails ?? [];
-  return { contacts: emails.map((email2) => ({ email: email2, status: null, subscribed: false })) };
+  const userIds = body?.userIds ?? [];
+  return {
+    contacts: [
+      ...emails.map((email2) => ({ email: email2, userId: null, status: null, subscribed: false })),
+      ...userIds.map((userId2) => ({ email: null, userId: userId2, status: null, subscribed: false }))
+    ]
+  };
 }
 function batches(items, recordOf) {
   const out = [];
@@ -1049,14 +1117,19 @@ function backfillOf(options) {
 function count(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
-function contactCounts(body) {
+var LATER_CONTACT_COUNTS = ["confirmationsSent", "unknownContacts", "conflicts"];
+function contactCounts(body, indexOf = (i) => i) {
   const counts = {
     created: count(body.created),
     updated: count(body.updated),
     suppressedSkipped: count(body.suppressedSkipped),
     overCapacity: count(body.overCapacity)
   };
-  if (typeof body.confirmationsSent === "number") counts.confirmationsSent = body.confirmationsSent;
+  for (const key of LATER_CONTACT_COUNTS) {
+    const value = body[key];
+    if (typeof value === "number") counts[key] = value;
+  }
+  if (Array.isArray(body.conflicted)) counts.conflicted = body.conflicted.map((row) => conflict(row, indexOf));
   return counts;
 }
 function addContactCounts(a, b) {
@@ -1066,11 +1139,20 @@ function addContactCounts(a, b) {
     suppressedSkipped: a.suppressedSkipped + b.suppressedSkipped,
     overCapacity: a.overCapacity + b.overCapacity
   };
-  if (a.confirmationsSent !== void 0 || b.confirmationsSent !== void 0) {
-    sum.confirmationsSent = (a.confirmationsSent ?? 0) + (b.confirmationsSent ?? 0);
+  for (const key of LATER_CONTACT_COUNTS) {
+    if (a[key] !== void 0 || b[key] !== void 0) sum[key] = (a[key] ?? 0) + (b[key] ?? 0);
   }
+  if (a.conflicted || b.conflicted) sum.conflicted = [...a.conflicted ?? [], ...b.conflicted ?? []];
   return sum;
 }
+function conflict(row, indexOf) {
+  return {
+    index: indexOf(count(row.index)),
+    userId: typeof row.userId === "string" ? row.userId : null,
+    email: typeof row.email === "string" ? row.email : null,
+    reason: String(row.reason)
+  };
+}
 function eventCounts(body) {
   return { created: count(body.created), duplicates: count(body.duplicates), unknownContacts: count(body.unknownContacts) };
 }
@@ -1092,8 +1174,11 @@ var CONTACTS = {
   key: "contacts",
   read: contactCounts,
   add: addContactCounts,
-  tally: (tally, counts) => {
-    tally.over_capacity += counts.overCapacity;
+  tally: (call, counts) => {
+    call.tally.over_capacity += counts.overCapacity;
+    call.tally.unknown_user_ids += counts.unknownContacts ?? 0;
+    call.tally.conflicts += counts.conflicts ?? 0;
+    if (counts.conflicted) call.conflicted.push(...counts.conflicted);
   }
 };
 var SIGNUPS = {
@@ -1101,15 +1186,16 @@ var SIGNUPS = {
   key: "signups",
   read: signupCounts,
   add: addSignupCounts,
-  tally: (tally, counts) => {
-    tally.over_capacity += counts.overCapacity;
-    tally.signups_limited += counts.limited;
+  tally: (call, counts) => {
+    call.tally.over_capacity += counts.overCapacity;
+    call.tally.signups_limited += counts.limited;
   }
 };
 function statuses(body) {
   const rows = Array.isArray(body.contacts) ? body.contacts : [];
   return rows.map((row) => ({
-    email: String(row.email ?? ""),
+    email: typeof row.email === "string" ? row.email : null,
+    userId: typeof row.userId === "string" ? row.userId : null,
     status: typeof row.status === "string" ? row.status : null,
     subscribed: row.subscribed === true
   }));

package/dist/index.d.cts

@@ -26,13 +26,15 @@ declare class AguMailError extends Error {
     });
 }
 
-type AguMailWarningCode = 'unknown_contacts' | 'over_capacity' | 'signups_limited' | 'history';
+type AguMailWarningCode = 'unknown_contacts' | 'over_capacity' | 'signups_limited' | 'history' | 'unknown_user_ids' | 'conflicts';
 /** Records AguMail took without an error, but dropped or held back. */
 interface AguMailWarning {
     code: AguMailWarningCode;
     message: string;
     /** How many records it covers, added up over the call or flush. */
     count: number;
+    /** On a `conflicts` warning: the contacts AguMail refused, and why. */
+    conflicted?: ContactConflict[];
 }
 interface AguMailOptions {
     /** Where the AguMail API lives. Defaults to https://api.agumail.com. */
@@ -54,7 +56,8 @@ interface AguMailOptions {
     /**
      * Called when AguMail took a call without an error but dropped or held back
      * some of it: events for unknown contacts, a full plan, rate-limited signups,
-     * or events old enough to count as history. It may be async.
+     * events old enough to count as history, a userId nobody has, or an email
+     * that belongs to someone else. It may be async.
      */
     onWarning?: ((warning: AguMailWarning) => void | Promise<void>) | undefined;
     /**
@@ -115,7 +118,15 @@ type Outcome<T, O> = O extends {
 /** A contact property. Sent to AguMail as text. */
 type PropertyValue = string | number | boolean | Date | null | undefined;
 interface Contact {
-    email: string;
+    /** Needed unless you pass userId. With a userId, it is the address the contact should have. */
+    email?: string | null | undefined;
+    /**
+     * Your app's own id for the person, up to 200 characters, sent exactly as you
+     * give it (a whole number is sent as text). AguMail then knows them by it: when
+     * they change their email in your app, identify moves the same contact to the
+     * new address. A contact keeps the first id it is sent with.
+     */
+    userId?: string | number | null | undefined;
     firstName?: string | null | undefined;
     lastName?: string | null | undefined;
     phone?: string | null | undefined;
@@ -132,9 +143,12 @@ interface Contact {
     /** When they became your customer. Becomes their "Date added" when AguMail creates them. */
     customerSince?: string | Date | null | undefined;
 }
-type ContactProfile = Omit<Contact, 'email' | 'subscribed'>;
+type ContactProfile = Omit<Contact, 'email' | 'userId' | 'subscribed'>;
 interface TrackEvent {
-    email: string;
+    /** Who did it. Needed unless you pass userId. */
+    email?: string | null | undefined;
+    /** Your app's own id for the person. With one, AguMail finds them by it alone, and reads no email. */
+    userId?: string | number | null | undefined;
     /** Your name for what happened, such as "Created first campaign". */
     event: string;
     /** Any plain object, nested or typed by your own interface. Sent as JSON. */
@@ -148,7 +162,11 @@ interface TrackEvent {
      * your whole account. One is generated when you leave it out.
      */
     uniqueId?: string | null | undefined;
-    /** Upserts the contact first, with these fields. Never changes their subscription. */
+    /**
+     * Upserts the contact first, with these fields and the event's email and userId.
+     * That upsert is an identify that never changes their subscription: with both
+     * email and userId, it can move the contact to that email.
+     */
     contact?: ContactProfile | null | undefined;
 }
 interface Signup {
@@ -180,6 +198,32 @@ interface ContactCounts {
     overCapacity: number;
     /** Sent by AguMail servers that report confirmation emails. */
     confirmationsSent?: number;
+    /**
+     * Contacts sent with only a userId that no contact has, so they were skipped:
+     * a new contact needs an email. Sent by AguMail servers that know user ids, as
+     * are conflicts and conflicted.
+     */
+    unknownContacts?: number;
+    /** Contacts refused because their email belongs to someone else. */
+    conflicts?: number;
+    /** Each contact refused, and why. AguMail never merges two contacts. */
+    conflicted?: ContactConflict[];
+}
+/**
+ * - `email_taken`: the userId's contact can't move to this email, because another contact has it.
+ * - `user_id_mismatch`: the contact with this email already has a different userId.
+ */
+type ContactConflictReason = 'email_taken' | 'user_id_mismatch';
+interface ContactConflict {
+    /**
+     * The record's place in the array you passed, from 0: the contact's for
+     * identifyMany, the event's for trackMany. In a flush, its place among the
+     * contacts that flush sent, in the order they were queued.
+     */
+    index: number;
+    userId: string | null;
+    email: string | null;
+    reason: ContactConflictReason;
 }
 interface EventCounts {
     created: number;
@@ -198,8 +242,11 @@ interface TrackManyResult extends EventCounts {
 }
 type ContactStatusValue = 'active' | 'nonsubscribed' | 'unconfirmed' | 'unsubscribed' | 'bounced' | 'complained' | 'cleaned';
 interface ContactStatus {
-    email: string;
-    /** null when the address is not on your list. */
+    /** The address asked about, or the contact's own when you asked by userId. null for an id nobody has. */
+    email: string | null;
+    /** The id asked about, or the contact's own when you asked by email. null when it has none, or nobody has the address. */
+    userId: string | null;
+    /** null when the address or id is not on your list. */
     status: ContactStatusValue | null;
     /** The one to act on: subscribed, and not unsubscribed or bounced since. */
     subscribed: boolean;
@@ -222,6 +269,7 @@ interface SignupCounts {
     limited: number;
 }
 interface PingResult {
+    /** `userId` is your AguMail account's id, not one of your app's user ids. */
     shop: {
         userId: string;
         shopName: string | null;
@@ -253,6 +301,21 @@ interface ContactsApi {
      * const answers = await agumail.contacts.status(['sam@example.com', 'alex@example.com']);
      */
     status<O extends CallOptions | undefined = undefined>(emails: readonly string[], options?: O): Promise<Outcome<ContactStatus[], O>>;
+    /**
+     * Where the contact with your app's user id stands, as status answers for an address.
+     * `email` is the address that contact has, and `status` is null for an id nobody has.
+     *
+     * @example
+     * const { subscribed } = await agumail.contacts.statusByUserId(user.id);
+     */
+    statusByUserId<O extends CallOptions | undefined = undefined>(userId: string | number, options?: O): Promise<Outcome<ContactStatus, O>>;
+    /**
+     * Where each user id stands, in the order you asked, 500 to a request.
+     *
+     * @example
+     * const answers = await agumail.contacts.statusByUserId(users.map((u) => u.id));
+     */
+    statusByUserId<O extends CallOptions | undefined = undefined>(userIds: readonly (string | number)[], options?: O): Promise<Outcome<ContactStatus[], O>>;
     /**
      * The person turned marketing email on, themselves, in your app's settings. Call it
      * only then: someone who left from an email gets one confirmation email instead.
@@ -288,6 +351,8 @@ interface QueueApi {
     /**
      * Queues a contact for the next flush, subscribed unless `subscribed: false`, as
      * with identify. Never throws: a bad record goes to onError and is not queued.
+     * A contact AguMail refuses because its email belongs to someone else is a
+     * `conflicts` warning, and is listed in the flush's result.
      *
      * @example
      * agumail.queue.identify({ email: user.email, firstName: user.firstName });
@@ -319,22 +384,27 @@ declare class AguMail {
     /**
      * Adds or updates a contact, and subscribes them unless you pass `subscribed: false`.
      * It never brings back someone who unsubscribed or bounced (`suppressedSkipped`).
+     * Pass your app's `userId` and AguMail knows them by it, so a changed email moves
+     * the same contact. A record that would mix two people up is refused without an
+     * error, and listed in `conflicted`.
      *
      * @example
-     * await agumail.identify({ email: 'sam@example.com', firstName: 'Sam' });
+     * await agumail.identify({ email: 'sam@example.com', userId: user.id, firstName: 'Sam' });
      */
     identify<O extends CallOptions | undefined = undefined>(contact: Contact, options?: O): Promise<Outcome<ContactCounts, O>>;
     /**
      * identify for any number of contacts, 500 to a request. Every record is checked
      * first, and nothing is sent if one is wrong. Pass `backfill: true` for an import.
+     * Each entry of `conflicted` gives its contact's place in your array as `index`.
      *
      * @example
      * await agumail.identifyMany(users.map((u) => ({ email: u.email, subscribed: u.marketingOptIn })), { backfill: true });
      */
     identifyMany<O extends BatchOptions | undefined = undefined>(contacts: readonly Contact[], options?: O): Promise<Outcome<ContactCounts, O>>;
     /**
-     * Records something a contact did. AguMail skips events for people it doesn't have,
-     * so identify them first, or pass `contact` to upsert them (never subscribed) first.
+     * Records something a contact did, named by email or by your app's `userId`. AguMail
+     * skips events for people it doesn't have, so identify them first, or pass `contact`
+     * to upsert them (never subscribed) first.
      *
      * @example
      * await agumail.track({ email: 'sam@example.com', event: 'Created project', uniqueId: `project:${id}` });
@@ -342,7 +412,8 @@ declare class AguMail {
     track<O extends CallOptions | undefined = undefined>(event: TrackEvent, options?: O): Promise<Outcome<TrackResult, O>>;
     /**
      * track for any number of events, 500 to a request, each batch's contacts first.
-     * On failure, `error.uniqueIds` holds the id each event was sent with.
+     * On failure, `error.uniqueIds` holds the id each event was sent with. A conflict
+     * in `contacts.conflicted` gives its event's place in your array as `index`.
      *
      * @example
      * const { uniqueIds } = await agumail.trackMany(rows.map((r) => ({ email: r.email, event: 'Imported' })));
@@ -371,4 +442,4 @@ declare class AguMail {
 declare const VERSION: string;
 
 export { AguMail, AguMailError, VERSION, noThrow };
-export type { AguMailErrorCode, AguMailErrorPartial, AguMailOptions, AguMailWarning, AguMailWarningCode, BatchOptions, CallOptions, Contact, ContactCounts, ContactProfile, ContactStatus, ContactStatusValue, ContactsApi, EventCounts, FlushOptions, FlushResult, Form, FormList, FormsApi, Outcome, PingResult, PropertyValue, QueueApi, Settled, Signup, SignupCounts, SignupsApi, TrackEvent, TrackManyResult, TrackResult };
+export type { AguMailErrorCode, AguMailErrorPartial, AguMailOptions, AguMailWarning, AguMailWarningCode, BatchOptions, CallOptions, Contact, ContactConflict, ContactConflictReason, ContactCounts, ContactProfile, ContactStatus, ContactStatusValue, ContactsApi, EventCounts, FlushOptions, FlushResult, Form, FormList, FormsApi, Outcome, PingResult, PropertyValue, QueueApi, Settled, Signup, SignupCounts, SignupsApi, TrackEvent, TrackManyResult, TrackResult };