@drawbridge/drawbridge-utils 0.0.154 → 0.0.156

package/dist/connections/index.d.ts

@@ -334,6 +334,10 @@ const WRITE_OPERATIONS = Object.freeze([ 'create', 'delete', 'update' ]);
 //   payload      the verified inbound body
 //   scope        the granted scope string being judged
 //   secret       the credential VALUE the caller resolved for verification
+//   segments     the non-system segments this contact is in, as { id, title },
+//                resolved by the shell — null when the run carried no contact
+//                document, which means nobody looked, where [] means they are
+//                in none. A hook handed null leaves the vendor's copy alone
 //   settings     the connection's decrypted settings
 //   step         the step document
 //   suppressed   the opt-out floor's answer for this lead, computed by the shell
@@ -383,7 +387,7 @@ const HOOK_PROPS = Object.freeze([
 	'channel', 'clientId', 'clientSecret', 'connection', 'contact', 'context',
 	'cursor', 'declaration', 'doc', 'email', 'event', 'headers', 'id', 'lead', 'limit',
 	'manifest', 'payload',
-	'scope', 'search', 'secret', 'settings', 'sort', 'step', 'suppressed',
+	'scope', 'search', 'secret', 'segments', 'settings', 'sort', 'step', 'suppressed',
 	'token', 'tokens', 'workflow'
 ]);
 
@@ -1516,10 +1520,15 @@ const contacts = {
 			remove : async ( { email, id, token }, { fetcher } = {} ) => {
 
 				// NO TOKEN IS A NO-OP HERE, unlike sendgrid and twilio, and the
-				// difference is what the credential is declared to be: hubspotToken
-				// is the one provider field that is not `required`, because this is
-				// internal CRM tooling no merchant sees. A deployment with no portal
-				// is a supported state, not a missing credential.
+				// difference is what the credential is FOR: this is internal CRM
+				// tooling no merchant sees, so a deployment with no portal is a
+				// supported state rather than a missing credential.
+				//
+				// The manifest does mark hubspotToken `required`, and that is not a
+				// contradiction — the flag feeds `isLive` and nothing else, so it
+				// decides whether the admin card reads live. Not live is the honest
+				// badge when nothing will sync. It gates no behaviour, and
+				// saveProviderSettings never consults it, so the row still writes.
 				if( ! token ) return;
 
 				const contact = id || await lookup({ email, fetcher, token });
@@ -2834,10 +2843,15 @@ var klaviyo = {
 
 		// HOW TO CONNECT, in the merchant's words. Was `setup`, which nothing
 		// rendered — four useful instructions no component displayed.
+		// NAMES THE LIST STEP, because `status` below gates on it: a grant with no
+		// list chosen sits at Pending, and this told the merchant it would show
+		// Active. The one required action was the one action the guide omitted, so
+		// anybody following it landed on a connection that looked broken.
 		guide : [
 			'Press Connect. Drawbridge sends you to Klaviyo to approve access.',
 			'Sign in to Klaviyo if you are not already, and choose the account to connect.',
-			'Approve the permissions Klaviyo lists. You are returned here and the connection shows Active.',
+			'Approve the permissions Klaviyo lists. You come back here to pick the list your contacts should sync into.',
+			'The connection shows Pending until you pick a list, then Active.',
 			'You can revoke access at any time from Klaviyo, under Integrations.'
 		]
 
@@ -2987,7 +3001,7 @@ var klaviyo = {
 			// different thing from deleting the profile.
 			remove : false,
 
-			sync : async ( { contact, lead, settings, suppressed, token }, { fetcher } = {} ) => {
+			sync : async ( { context, lead, segments, settings, suppressed, token }, { fetcher } = {} ) => {
 
 				const list = settings?.list;
 
@@ -3005,9 +3019,32 @@ var klaviyo = {
 				// contact knows money: order attribution is person-level and merges
 				// across every address a human used, so revenue and orders cannot
 				// exist on a single-address record.
-				const totals = contact?.totals || {};
-
-				const profile = await api$1( '/profiles/', {
+				//
+				// READ OFF `context`, NOT the shell's `contact` prop. That prop is the
+				// ADDRESS — a string — so `contact?.totals` was undefined on every run
+				// this hook has ever made, and all five properties below shipped as 0
+				// no matter what the person had entered, drawn or spent. Only a
+				// segment.contact.add run carries the document (drawbridge-sync
+				// lib/segment.js); lead.insert names a brand-new entrant who has no
+				// history to send anyway.
+				const person = context?.contact || null;
+				const totals = person?.totals || {};
+
+				// UPSERT, NOT CREATE. /profiles/ is the plain create and answers a
+				// conflict for a profile Klaviyo already holds — which is most of them,
+				// because the whole point of the segment trigger is syncing people who
+				// have been around long enough to earn a ranking. profile-import is
+				// Klaviyo's documented create-or-update: 201 when it made one, 200 when
+				// it updated one, and no conflict either way
+				// (developers.klaviyo.com/en/reference/create_or_update_profile,
+				// fetched 2026-09-09).
+				//
+				// IT MERGES, and that is why the blocks below are conditional rather
+				// than defaulted. "Not including a field in your request will leave it
+				// unchanged" — so omitting the totals on a lead.insert preserves
+				// whatever the last segment run published, where sending zeros would
+				// erase it. A property we cannot compute is one we must not write.
+				const profile = await api$1( '/profile-import', {
 					fetcher,
 					method : 'POST',
 					payload : {
@@ -3016,16 +3053,36 @@ var klaviyo = {
 								email,
 								...( lead?.name && { first_name : String( lead.name ).trim().split( /\s+/ )[ 0 ] }),
 								properties : {
-									drawbridge_campaigns : ( contact?.campaigns || [] ).length,
-									drawbridge_draws : totals.draws || 0,
-									drawbridge_entries : totals.entries || 0,
-									drawbridge_orders : totals.orders || 0,
-									// Campaign-attributed, NOT lifetime. A merchant running
-									// Shopify already has lifetime revenue in Klaviyo through
-									// Klaviyo's own integration; what only we can say is how
-									// much a campaign drove. Named so the two cannot be
-									// mistaken for one another in a segment builder.
-									drawbridge_revenue : totals.gross || 0
+									...( person && {
+										drawbridge_campaigns : ( person.campaigns || [] ).length,
+										drawbridge_draws : totals.draws || 0,
+										drawbridge_entries : totals.entries || 0,
+										drawbridge_orders : totals.orders || 0,
+										// Campaign-attributed, NOT lifetime. A merchant running
+										// Shopify already has lifetime revenue in Klaviyo through
+										// Klaviyo's own integration; what only we can say is how
+										// much a campaign drove. Named so the two cannot be
+										// mistaken for one another in a segment builder.
+										drawbridge_revenue : totals.gross || 0
+									}),
+									// THE DRAWBRIDGE SEGMENTS THEY ARE IN, as a list property the
+									// merchant builds Klaviyo segments on top of. Klaviyo owns no
+									// writable membership — its segments are computed from rules,
+									// so a profile cannot be put in one — and this is the nearest
+									// honest equivalent.
+									//
+									// WHOLESALE, WHICH IS WHAT MAKES IT SELF-HEALING. Drawbridge
+									// segments are dynamic and nothing dispatches a leave event —
+									// only segment.contact.add exists — so a property that was
+									// only ever appended to would outlive the membership that
+									// earned it. Rewriting the whole array each run means every
+									// sync corrects whatever the last one got wrong, with no
+									// removal path to build.
+									//
+									// `segments` is null when the run carried no contact document,
+									// meaning nobody looked — different from [], which means they
+									// are in none. Null omits the key and merge leaves it alone.
+									...( segments && { drawbridge_segments : segments.map( ( entry ) => entry.title ).filter( Boolean ) })
 								}
 							},
 							type : 'profile'
@@ -3427,7 +3484,10 @@ const api = async ( path, { dc, fetcher = fetch, method = 'GET', payload, token
 
 	}
 
-	return response.json();
+	// 204 ON A TAG WRITE — nothing to parse, and asking an empty body for json
+	// throws, which would report a change Mailchimp accepted as a failed step.
+	// Klaviyo's file carries the same guard for the same reason.
+	return response.status === 204 ? null : response.json();
 
 };
 
@@ -3591,7 +3651,7 @@ var mailchimp = {
 			// PUT /lists/{list_id}/members/{subscriber_hash} — an UPSERT, which is
 			// why there is no create-or-update branch here. Quoted from Mailchimp's
 			// Marketing API reference for the list-members resource.
-			sync : async ( { lead, settings, suppressed, token }, { fetcher } = {} ) => {
+			sync : async ( { connection, lead, segments, settings, suppressed, token }, { fetcher, read } = {} ) => {
 
 				const audience = settings?.audience;
 
@@ -3648,6 +3708,75 @@ var mailchimp = {
 					token
 				});
 
+				// THE DRAWBRIDGE SEGMENTS THIS PERSON IS IN, written as Mailchimp tags.
+				//
+				// TAGS, NOT MERGE FIELDS. A merge field has to exist on the audience
+				// before anything can be written to it, and an unregistered one is
+				// refused along with the whole member request — so carrying data that
+				// way means registering fields first, which is lifecycle.register's job
+				// and is not built. A tag needs no setup: "If a tag that does not exist
+				// is passed in and set as 'active', a new tag will be created"
+				// (mailchimp.com/developer/marketing/api/list-member-tags/add-or-remove-member-tags,
+				// fetched 2026-09-09). Nothing for the merchant to prepare, so nothing
+				// to explain in the guide.
+				//
+				// ACTIVE AND INACTIVE IN ONE CALL, which is what keeps this correct
+				// over time. Drawbridge segments are dynamic, and nothing dispatches a
+				// leave event — only segment.contact.add exists — so a tag that was
+				// only ever added would outlive the membership behind it and the
+				// merchant would target a condition that had stopped being true.
+				// Sending the whole list every time, each tag active or inactive
+				// against current membership, means each sync corrects the last.
+				//
+				// WRITTEN FOR A SUPPRESSED PERSON TOO. A tag is a label, not a
+				// permission: the `status : 'unsubscribed'` above is what stops mail
+				// reaching them, and letting their labels rot would leave the merchant
+				// a wrong answer about who belongs to what.
+				//
+				// PREFIXED, so a Drawbridge tag cannot collide with one the merchant
+				// keeps by hand, and so the inactive pass can only clear tags this
+				// integration wrote.
+				if( segments && read ){
+
+					const owned = await read.aggregate({
+						collection : 'segment',
+						pipeline : [
+							{
+								$match : {
+									organization : connection?.organization,
+									system : { $ne : true }
+								}
+							},
+							{
+								$project : { _id : 0, title : 1 }
+							}
+						]
+					});
+
+					const joined = new Set( segments.map( ( entry ) => entry.title ) );
+
+					const tags = ( owned || [] )
+						.map( ( entry ) => entry.title )
+						.filter( Boolean )
+						.map( ( title ) => ({
+							name : 'Drawbridge: ' + title,
+							status : joined.has( title ) ? 'active' : 'inactive'
+						}) );
+
+					if( tags.length > 0 ){
+
+						await api( '/lists/' + audience + '/members/' + hash + '/tags', {
+							dc : settings?.dc,
+							fetcher,
+							method : 'POST',
+							payload : { tags },
+							token
+						});
+
+					}
+
+				}
+
 				return {
 					// Merged into `context` for later steps in this run.
 					context : { mailchimpMemberId : member?.id || hash },
@@ -5765,9 +5894,14 @@ var webhook = {
 			'Generate a signing secret and Drawbridge signs every request with it. Your endpoint recomputes the signature to confirm each payload genuinely came from Drawbridge before acting on it.'
 		],
 		excerpt : 'Sign outgoing webhook payloads with an HMAC secret to verify authenticity.',
+		// SAYS WHERE THE URL GOES. Connecting only mints a secret, so a merchant
+		// following this had nowhere to put the endpoint they came to configure —
+		// the destination lives on the step (see steps.webhook.send.settings), and
+		// the guide never said so.
 		guide : [
 			'Press Connect. Drawbridge generates a signing secret and shows it here.',
 			'Copy the secret into your own endpoint.',
+			'Add a Send webhook step to a workflow and put your endpoint URL on it. The URL belongs to the step rather than the connection, so one connection can serve several endpoints.',
 			'On each request, compute HMAC-SHA256 of the raw body using the secret and compare it against the X-Drawbridge-Signature header before acting on the payload.'
 		]
 	},

package/dist/connections/index.js

@@ -199,6 +199,7 @@ var HOOK_PROPS = Object.freeze([
   "scope",
   "search",
   "secret",
+  "segments",
   "settings",
   "sort",
   "step",
@@ -2592,10 +2593,15 @@ var klaviyo_default2 = {
     excerpt: "Sync the contacts your campaigns collect into a Klaviyo list.",
     // HOW TO CONNECT, in the merchant's words. Was `setup`, which nothing
     // rendered — four useful instructions no component displayed.
+    // NAMES THE LIST STEP, because `status` below gates on it: a grant with no
+    // list chosen sits at Pending, and this told the merchant it would show
+    // Active. The one required action was the one action the guide omitted, so
+    // anybody following it landed on a connection that looked broken.
     guide: [
       "Press Connect. Drawbridge sends you to Klaviyo to approve access.",
       "Sign in to Klaviyo if you are not already, and choose the account to connect.",
-      "Approve the permissions Klaviyo lists. You are returned here and the connection shows Active.",
+      "Approve the permissions Klaviyo lists. You come back here to pick the list your contacts should sync into.",
+      "The connection shows Pending until you pick a list, then Active.",
       "You can revoke access at any time from Klaviyo, under Integrations."
     ]
   },
@@ -2717,14 +2723,15 @@ var klaviyo_default2 = {
       // Not yet. Suppression syncs an opt-out as unsubscribed, which is a
       // different thing from deleting the profile.
       remove: false,
-      sync: async ({ contact, lead, settings, suppressed, token }, { fetcher } = {}) => {
+      sync: async ({ context, lead, segments, settings, suppressed, token }, { fetcher } = {}) => {
         var _a, _b, _c;
         const list = settings == null ? void 0 : settings.list;
         if (!list) return { message: "No Klaviyo list is chosen for this connection.", skipped: true };
         const email = ((_b = (_a = lead == null ? void 0 : lead.canonical) == null ? void 0 : _a.email) == null ? void 0 : _b.value) || (lead == null ? void 0 : lead.email);
         if (!email) return { message: "That lead has no email address to sync.", skipped: true };
-        const totals = (contact == null ? void 0 : contact.totals) || {};
-        const profile = await api2("/profiles/", {
+        const person = (context == null ? void 0 : context.contact) || null;
+        const totals = (person == null ? void 0 : person.totals) || {};
+        const profile = await api2("/profile-import", {
           fetcher,
           method: "POST",
           payload: {
@@ -2733,16 +2740,36 @@ var klaviyo_default2 = {
                 email,
                 ...(lead == null ? void 0 : lead.name) && { first_name: String(lead.name).trim().split(/\s+/)[0] },
                 properties: {
-                  drawbridge_campaigns: ((contact == null ? void 0 : contact.campaigns) || []).length,
-                  drawbridge_draws: totals.draws || 0,
-                  drawbridge_entries: totals.entries || 0,
-                  drawbridge_orders: totals.orders || 0,
-                  // Campaign-attributed, NOT lifetime. A merchant running
-                  // Shopify already has lifetime revenue in Klaviyo through
-                  // Klaviyo's own integration; what only we can say is how
-                  // much a campaign drove. Named so the two cannot be
-                  // mistaken for one another in a segment builder.
-                  drawbridge_revenue: totals.gross || 0
+                  ...person && {
+                    drawbridge_campaigns: (person.campaigns || []).length,
+                    drawbridge_draws: totals.draws || 0,
+                    drawbridge_entries: totals.entries || 0,
+                    drawbridge_orders: totals.orders || 0,
+                    // Campaign-attributed, NOT lifetime. A merchant running
+                    // Shopify already has lifetime revenue in Klaviyo through
+                    // Klaviyo's own integration; what only we can say is how
+                    // much a campaign drove. Named so the two cannot be
+                    // mistaken for one another in a segment builder.
+                    drawbridge_revenue: totals.gross || 0
+                  },
+                  // THE DRAWBRIDGE SEGMENTS THEY ARE IN, as a list property the
+                  // merchant builds Klaviyo segments on top of. Klaviyo owns no
+                  // writable membership — its segments are computed from rules,
+                  // so a profile cannot be put in one — and this is the nearest
+                  // honest equivalent.
+                  //
+                  // WHOLESALE, WHICH IS WHAT MAKES IT SELF-HEALING. Drawbridge
+                  // segments are dynamic and nothing dispatches a leave event —
+                  // only segment.contact.add exists — so a property that was
+                  // only ever appended to would outlive the membership that
+                  // earned it. Rewriting the whole array each run means every
+                  // sync corrects whatever the last one got wrong, with no
+                  // removal path to build.
+                  //
+                  // `segments` is null when the run carried no contact document,
+                  // meaning nobody looked — different from [], which means they
+                  // are in none. Null omits the key and merge leaves it alone.
+                  ...segments && { drawbridge_segments: segments.map((entry) => entry.title).filter(Boolean) }
                 }
               },
               type: "profile"
@@ -3034,7 +3061,7 @@ var api3 = async (path, { dc, fetcher = fetch, method = "GET", payload, token })
       { status: response.status }
     );
   }
-  return response.json();
+  return response.status === 204 ? null : response.json();
 };
 var subscriberHash = (email) => createHash2("md5").update(String(email).trim().toLowerCase()).digest("hex");
 var mailchimp_default2 = {
@@ -3168,7 +3195,7 @@ var mailchimp_default2 = {
       // PUT /lists/{list_id}/members/{subscriber_hash} — an UPSERT, which is
       // why there is no create-or-update branch here. Quoted from Mailchimp's
       // Marketing API reference for the list-members resource.
-      sync: async ({ lead, settings, suppressed, token }, { fetcher } = {}) => {
+      sync: async ({ connection: connection2, lead, segments, settings, suppressed, token }, { fetcher, read } = {}) => {
         var _a, _b;
         const audience = settings == null ? void 0 : settings.audience;
         if (!audience) return { message: "No Mailchimp audience is chosen for this connection.", skipped: true };
@@ -3194,6 +3221,36 @@ var mailchimp_default2 = {
           },
           token
         });
+        if (segments && read) {
+          const owned = await read.aggregate({
+            collection: "segment",
+            pipeline: [
+              {
+                $match: {
+                  organization: connection2 == null ? void 0 : connection2.organization,
+                  system: { $ne: true }
+                }
+              },
+              {
+                $project: { _id: 0, title: 1 }
+              }
+            ]
+          });
+          const joined = new Set(segments.map((entry) => entry.title));
+          const tags = (owned || []).map((entry) => entry.title).filter(Boolean).map((title) => ({
+            name: "Drawbridge: " + title,
+            status: joined.has(title) ? "active" : "inactive"
+          }));
+          if (tags.length > 0) {
+            await api3("/lists/" + audience + "/members/" + hash + "/tags", {
+              dc: settings == null ? void 0 : settings.dc,
+              fetcher,
+              method: "POST",
+              payload: { tags },
+              token
+            });
+          }
+        }
         return {
           // Merged into `context` for later steps in this run.
           context: { mailchimpMemberId: (member == null ? void 0 : member.id) || hash },
@@ -4862,9 +4919,14 @@ var webhook_default = {
       "Generate a signing secret and Drawbridge signs every request with it. Your endpoint recomputes the signature to confirm each payload genuinely came from Drawbridge before acting on it."
     ],
     excerpt: "Sign outgoing webhook payloads with an HMAC secret to verify authenticity.",
+    // SAYS WHERE THE URL GOES. Connecting only mints a secret, so a merchant
+    // following this had nowhere to put the endpoint they came to configure —
+    // the destination lives on the step (see steps.webhook.send.settings), and
+    // the guide never said so.
     guide: [
       "Press Connect. Drawbridge generates a signing secret and shows it here.",
       "Copy the secret into your own endpoint.",
+      "Add a Send webhook step to a workflow and put your endpoint URL on it. The URL belongs to the step rather than the connection, so one connection can serve several endpoints.",
       "On each request, compute HMAC-SHA256 of the raw body using the secret and compare it against the X-Drawbridge-Signature header before acting on the payload."
     ]
   },

package/dist/email.cjs

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // lib/email.js
 var email_exports = {};
 __export(email_exports, {
+  subAddress: () => subAddress,
   toCanonicalEmail: () => toCanonicalEmail
 });
 module.exports = __toCommonJS(email_exports);
@@ -36,7 +37,20 @@ var toCanonicalEmail = (value) => {
   if (!local) return null;
   return local + "@" + domain;
 };
+var LOCAL_PART_LIMIT = 64;
+var subAddress = (email, tag) => {
+  if (!email || typeof email !== "string") return email;
+  if (!tag || typeof tag !== "string") return email;
+  if (!/^[A-Za-z0-9]+$/.test(tag)) return email;
+  const at = email.lastIndexOf("@");
+  if (at < 1 || at === email.length - 1) return email;
+  const local = email.slice(0, at);
+  if (local.includes("+")) return email;
+  if (local.length + 1 + tag.length > LOCAL_PART_LIMIT) return email;
+  return local + "+" + tag + "@" + email.slice(at + 1);
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  subAddress,
   toCanonicalEmail
 });

package/dist/email.d.cts

@@ -33,4 +33,56 @@ const toCanonicalEmail = ( value ) => {
 
 };
 
-export { toCanonicalEmail };
+// RFC 5322 caps the local part at 64 octets. Everything here is ASCII, so
+// length is octets.
+const LOCAL_PART_LIMIT = 64;
+
+// The inverse of toCanonicalEmail: put a tag INTO the local part rather than
+// strip one out. `subAddress( 'org@send.drwbrdg.com', '507f…' )` gives
+// `org+507f…@send.drwbrdg.com` — RFC 5233 sub-addressing, which Google delivers
+// to the untagged mailbox natively.
+//
+// This is how the platform's lead-facing sender carries the ORGANIZATION.
+// Shopify does the same thing with `store+<shopId>@shopifyemail.com`: one
+// mailbox, one MX record, one authenticated domain, and the tenant rides in the
+// address instead of in infrastructure. There is no per-organization address to
+// store, so there is nothing to migrate or backfill.
+//
+// It is derived at send time, never persisted. Worth settling BEFORE the first
+// send rather than after: the From line is frozen into every message already
+// delivered, so a shared address cannot be split apart retroactively.
+//
+// Returns the address UNCHANGED whenever it cannot be tagged safely — a flat
+// from-address is a working email, a malformed one is a send the provider
+// rejects outright. Callers rely on that: the sender resolvers fall through to
+// their own defaults on a falsy return, and never on a broken string.
+const subAddress = ( email, tag ) => {
+
+	if( ! email || typeof email !== 'string' ) return email;
+	if( ! tag || typeof tag !== 'string' ) return email;
+
+	// Organization ids are 24-char ObjectId hex, and the short-id generator is
+	// base36 — both alphanumeric, both safely atext. Checked rather than assumed
+	// because the api schema types `id` as a bare string with no pattern, and
+	// `formats.documents.insert` spreads caller data OVER the generated id, so a
+	// hand-written id would win.
+	if( ! /^[A-Za-z0-9]+$/.test( tag ) ) return email;
+
+	const at = email.lastIndexOf( '@' );
+
+	if( at < 1 || at === email.length - 1 ) return email;
+
+	const local = email.slice( 0, at );
+
+	// Already tagged. Re-tagging would nest (`org+a+b@`), and the first tag is
+	// the one a receiving mailbox would route on — so the second would be a
+	// silent lie about which tenant the mail belongs to.
+	if( local.includes( '+' ) ) return email;
+
+	if( local.length + 1 + tag.length > LOCAL_PART_LIMIT ) return email;
+
+	return local + '+' + tag + '@' + email.slice( at + 1 );
+
+};
+
+export { subAddress, toCanonicalEmail };

package/dist/email.d.ts

@@ -33,4 +33,56 @@ const toCanonicalEmail = ( value ) => {
 
 };
 
-export { toCanonicalEmail };
+// RFC 5322 caps the local part at 64 octets. Everything here is ASCII, so
+// length is octets.
+const LOCAL_PART_LIMIT = 64;
+
+// The inverse of toCanonicalEmail: put a tag INTO the local part rather than
+// strip one out. `subAddress( 'org@send.drwbrdg.com', '507f…' )` gives
+// `org+507f…@send.drwbrdg.com` — RFC 5233 sub-addressing, which Google delivers
+// to the untagged mailbox natively.
+//
+// This is how the platform's lead-facing sender carries the ORGANIZATION.
+// Shopify does the same thing with `store+<shopId>@shopifyemail.com`: one
+// mailbox, one MX record, one authenticated domain, and the tenant rides in the
+// address instead of in infrastructure. There is no per-organization address to
+// store, so there is nothing to migrate or backfill.
+//
+// It is derived at send time, never persisted. Worth settling BEFORE the first
+// send rather than after: the From line is frozen into every message already
+// delivered, so a shared address cannot be split apart retroactively.
+//
+// Returns the address UNCHANGED whenever it cannot be tagged safely — a flat
+// from-address is a working email, a malformed one is a send the provider
+// rejects outright. Callers rely on that: the sender resolvers fall through to
+// their own defaults on a falsy return, and never on a broken string.
+const subAddress = ( email, tag ) => {
+
+	if( ! email || typeof email !== 'string' ) return email;
+	if( ! tag || typeof tag !== 'string' ) return email;
+
+	// Organization ids are 24-char ObjectId hex, and the short-id generator is
+	// base36 — both alphanumeric, both safely atext. Checked rather than assumed
+	// because the api schema types `id` as a bare string with no pattern, and
+	// `formats.documents.insert` spreads caller data OVER the generated id, so a
+	// hand-written id would win.
+	if( ! /^[A-Za-z0-9]+$/.test( tag ) ) return email;
+
+	const at = email.lastIndexOf( '@' );
+
+	if( at < 1 || at === email.length - 1 ) return email;
+
+	const local = email.slice( 0, at );
+
+	// Already tagged. Re-tagging would nest (`org+a+b@`), and the first tag is
+	// the one a receiving mailbox would route on — so the second would be a
+	// silent lie about which tenant the mail belongs to.
+	if( local.includes( '+' ) ) return email;
+
+	if( local.length + 1 + tag.length > LOCAL_PART_LIMIT ) return email;
+
+	return local + '+' + tag + '@' + email.slice( at + 1 );
+
+};
+
+export { subAddress, toCanonicalEmail };

package/dist/email.js

@@ -13,6 +13,19 @@ var toCanonicalEmail = (value) => {
   if (!local) return null;
   return local + "@" + domain;
 };
+var LOCAL_PART_LIMIT = 64;
+var subAddress = (email, tag) => {
+  if (!email || typeof email !== "string") return email;
+  if (!tag || typeof tag !== "string") return email;
+  if (!/^[A-Za-z0-9]+$/.test(tag)) return email;
+  const at = email.lastIndexOf("@");
+  if (at < 1 || at === email.length - 1) return email;
+  const local = email.slice(0, at);
+  if (local.includes("+")) return email;
+  if (local.length + 1 + tag.length > LOCAL_PART_LIMIT) return email;
+  return local + "+" + tag + "@" + email.slice(at + 1);
+};
 export {
+  subAddress,
   toCanonicalEmail
 };