@drawbridge/drawbridge-utils 0.0.134 → 0.0.136

package/dist/connections/index.d.cts

@@ -741,8 +741,12 @@ const accessToken = async ({
 
 		// Expired with no way to mint another. Said plainly rather than returning
 		// a token the vendor will refuse — the merchant has to reconnect and the
-		// error should say so.
-		throw new Error( 'This connection has expired and cannot be renewed automatically. Reconnect it.' );
+		// error should say so. Same `code` as a refused refresh: both mean the
+		// grant is dead and only reconnecting revives it.
+		throw Object.assign(
+			new Error( 'This connection has expired and cannot be renewed automatically. Reconnect it.' ),
+			{ code : 'grant_refused' }
+		);
 
 	}
 
@@ -1659,19 +1663,25 @@ const teamRecipients = async ({ memberIds = [], organization, read }) => {
 	// different teammates collapse into one and the second is never told.
 	const seen = new Set();
 
-	return [ owner, ...members ].filter( ( member ) => {
+	// THE ORG DOCUMENT COMES BACK TOO. It was read here anyway, and notify names
+	// the organization in its copy — a teammate can belong to more than one, so
+	// re-reading it there would be a second query for a document this already has.
+	return {
+		org,
+		recipients : [ owner, ...members ].filter( ( member ) => {
 
-		if( ! member?.id || ! member?.email ) return false;
+			if( ! member?.id || ! member?.email ) return false;
 
-		const address = member.email.toLowerCase();
+			const address = member.email.toLowerCase();
 
-		if( seen.has( address ) ) return false;
+			if( seen.has( address ) ) return false;
 
-		seen.add( address );
+			seen.add( address );
 
-		return true;
+			return true;
 
-	});
+		})
+	};
 
 };
 
@@ -1764,7 +1774,7 @@ var drawbridge = {
 				// mail the merchant did not ask for and would learn to ignore.
 				if( ! count ) return { message : 'No new leads in the period — digest skipped.', request, response : { skipped : true }, skipped : true };
 
-				const recipients = await teamRecipients({
+				const { recipients } = await teamRecipients({
 					memberIds : step.settings?.members || [],
 					organization : workflow.organization,
 					read
@@ -1805,7 +1815,7 @@ var drawbridge = {
 
 				const request = { members : memberIds.length };
 
-				const recipients = await teamRecipients({ memberIds, organization : workflow.organization, read });
+				const { org, recipients } = await teamRecipients({ memberIds, organization : workflow.organization, read });
 
 				if( ! recipients.length ){
 
@@ -1838,6 +1848,43 @@ var drawbridge = {
 				// to redefine from here.
 				const bucket = Math.floor( Date.now() / ( 15 * 60 * 1000 ) );
 
+				// THE COPY IS OURS, not the merchant's — `step.settings.message` and
+				// `.subject` are ignored here on purpose. The whole message is "a lead
+				// arrived, go and look", so the useful part is the link, not the
+				// wording.
+				//
+				// It NAMES THE CAMPAIGN AND THE ORGANIZATION, because a recipient can
+				// be watching several of both and a subject line reading only "New
+				// lead" makes them open the mail to find out which. The campaign title
+				// is the one extra read this step makes; the org came back with the
+				// recipients.
+				const campaign = context?.campaign
+					? await read.get({ collection : 'campaign', query : { id : context.campaign } })
+					: null;
+
+				// The href is DASHBOARD-RELATIVE: a manifest must not read
+				// process.env (see lib/connections/index.js), so the deployment's base
+				// url is applied by the sender — drawbridge-sync's queue/notification.js
+				// — before it renders. Absent a campaign or lead on the context there
+				// is nothing to point at, and no button is drawn.
+				const link = ( context?.campaign && context?.lead )
+					? {
+						href : '/organizations/' + workflow.organization + '/campaigns/' + context.campaign + '/leads/' + context.lead,
+						text : 'View lead'
+					}
+					: null;
+
+				// Every part is optional and every part is dropped when it is missing,
+				// so the worst case reads 'Someone just entered.' rather than a
+				// sentence with holes in it.
+				const body = ( context?.email || 'Someone' )
+					+ ' just entered'
+					+ ( campaign?.title ? ' ' + campaign.title : '' )
+					+ ( org?.title ? ' at ' + org.title : '' )
+					+ '.';
+
+				const subject = 'New lead' + ( campaign?.title ? ' — ' + campaign.title : '' );
+
 				return {
 					message : 'Team notification queued for ' + recipients.length + ' recipient(s).',
 					request,
@@ -1849,10 +1896,11 @@ var drawbridge = {
 							// can never swallow another's mail and a later bucket is never
 							// mistaken for a duplicate of an earlier one.
 							key : 'team.notify.' + workflow.id + '.' + member.id + '.' + bucket,
-							message : interpolate( step.settings?.message, context ),
+							link,
+							message : body,
 							organization : workflow.organization,
 							send : { type : 'email', email : member.email },
-							title : interpolate( step.settings?.subject, context ),
+							title : subject,
 							workflow : workflow.id
 						}),
 						// E11000 IS THE DAMPER WORKING: this recipient has already been
@@ -2412,14 +2460,24 @@ var drawbridge = {
 
 			// To organization MEMBERS. Never suppressed — an entrant's opt-out must
 			// not silence an alert to staff — and not billed.
+			//
+			// ITS COPY IS WRITTEN, NOT ASKED FOR. This says the same thing every
+			// time — a lead arrived, here it is — so the merchant chooses who hears
+			// it, not how it reads, and the hook composes the subject, the body and
+			// the link to the lead.
+			//
+			// `message` and `subject` stay declared, optional and IGNORED: stored
+			// workflows still carry them and the api validates settings with
+			// noUnknown().strict(), so dropping the keys would 400 the next save of
+			// a workflow built before this.
 			notify : () => ({
 				hook : 'email.notify',
 				key : 'Email — Notification',
 				queue : 'notification',
 				settings : {
 					members : { of : 'string', type : 'array' },
-					message : { required : true, type : 'string' },
-					subject : { required : true, type : 'string' }
+					message : { type : 'string' },
+					subject : { type : 'string' }
 				},
 				triggers : [ 'lead.insert' ],
 				// Zero is a PRICE, and a deliberate one. Declared rather than omitted
@@ -2941,8 +2999,84 @@ var klaviyo = {
 		inbound : false,
 
 		// Nothing to set up or tear down at the vendor: the grant is the whole
-		// integration, and revoking it is auth.disconnect's job.
-		lifecycle : false,
+		// integration. What CAN rot is the grant itself, so health is the one
+		// lifecycle hook Klaviyo carries.
+		lifecycle : {
+
+			// Nothing to set up, tear down, or re-register at the vendor — the
+			// grant is the whole integration.
+			cleanup : false,
+			register : false,
+			rehydrate : false,
+
+			// KEEP THE GRANT PROVEN AND WARM. The shell mints a fresh access
+			// token before every hook run — for Klaviyo that spends the refresh
+			// token, which is the only question that reaches Klaviyo (see
+			// auth.probe) — so this body running at all proves the grant still
+			// rotates, and the daily run keeps it inside Klaviyo's 90-day idle
+			// window. A dead grant never gets here: the shell's mint throws
+			// `grant_refused` and the step runner errors the connection itself.
+			//
+			// The one call below proves the minted token is HONOURED — mint and
+			// acceptance are different facts, and /accounts is already the call
+			// the connect flow makes (auth.connect), so it needs no new scope.
+			health : async ( { connection, token }, { fetcher, read } = {} ) => {
+
+				const request = { connectionId : connection.id };
+
+				try {
+
+					await api$1( '/accounts', { fetcher, token });
+
+					return {
+						message : 'Health check passed — token minted and accepted.',
+						request,
+						response : { pingedAt : new Date() }
+					};
+
+				} catch ( error ) {
+
+					// The token we JUST minted was refused — a revoked or
+					// downgraded grant, never a transient. The write rides out
+					// on the rejection (the shell performs a thrown error's
+					// effects) because the step must still fail.
+					if( [ 401, 403 ].includes( error.status ) && read ){
+
+						const current = await read.get({ collection : 'connection', query : { id : connection.id } });
+
+						if( current ){
+
+							const others = ( current.errors || [] ).filter( ( entry ) => entry.source !== 'oauth' );
+
+							error.writes = [ {
+								collection : 'connection',
+								data : {
+									$set : {
+										errors : [
+											...others,
+											{
+												message : 'Klaviyo no longer accepts this connection. Reconnect Klaviyo to resume syncing.',
+												source : 'oauth'
+											}
+										],
+										status : 'error'
+									}
+								},
+								operation : 'update',
+								query : { id : connection.id }
+							} ];
+
+						}
+
+					}
+
+					throw error;
+
+				}
+
+			}
+
+		},
 
 		resources : {
 
@@ -3049,6 +3183,22 @@ var klaviyo = {
 
 	steps : {
 
+		connection : {
+
+			// The daily grant check — same step type and workflow shape as
+			// Shopify's, provisioned as a system workflow per connection.
+			health : {
+				check : () => ({
+					description : 'Keeps the Klaviyo grant working — spends the refresh token daily so a revoked or idle grant is reported instead of discovered by a failing sync.',
+					hook : 'lifecycle.health',
+					key : 'Klaviyo Connection Health',
+					queue : 'connection',
+					system : true
+				})
+			}
+
+		},
+
 		contacts : {
 
 			// A DECLARATION, not the work. It names the hook that does the work, and

package/dist/connections/index.d.ts

@@ -741,8 +741,12 @@ const accessToken = async ({
 
 		// Expired with no way to mint another. Said plainly rather than returning
 		// a token the vendor will refuse — the merchant has to reconnect and the
-		// error should say so.
-		throw new Error( 'This connection has expired and cannot be renewed automatically. Reconnect it.' );
+		// error should say so. Same `code` as a refused refresh: both mean the
+		// grant is dead and only reconnecting revives it.
+		throw Object.assign(
+			new Error( 'This connection has expired and cannot be renewed automatically. Reconnect it.' ),
+			{ code : 'grant_refused' }
+		);
 
 	}
 
@@ -1659,19 +1663,25 @@ const teamRecipients = async ({ memberIds = [], organization, read }) => {
 	// different teammates collapse into one and the second is never told.
 	const seen = new Set();
 
-	return [ owner, ...members ].filter( ( member ) => {
+	// THE ORG DOCUMENT COMES BACK TOO. It was read here anyway, and notify names
+	// the organization in its copy — a teammate can belong to more than one, so
+	// re-reading it there would be a second query for a document this already has.
+	return {
+		org,
+		recipients : [ owner, ...members ].filter( ( member ) => {
 
-		if( ! member?.id || ! member?.email ) return false;
+			if( ! member?.id || ! member?.email ) return false;
 
-		const address = member.email.toLowerCase();
+			const address = member.email.toLowerCase();
 
-		if( seen.has( address ) ) return false;
+			if( seen.has( address ) ) return false;
 
-		seen.add( address );
+			seen.add( address );
 
-		return true;
+			return true;
 
-	});
+		})
+	};
 
 };
 
@@ -1764,7 +1774,7 @@ var drawbridge = {
 				// mail the merchant did not ask for and would learn to ignore.
 				if( ! count ) return { message : 'No new leads in the period — digest skipped.', request, response : { skipped : true }, skipped : true };
 
-				const recipients = await teamRecipients({
+				const { recipients } = await teamRecipients({
 					memberIds : step.settings?.members || [],
 					organization : workflow.organization,
 					read
@@ -1805,7 +1815,7 @@ var drawbridge = {
 
 				const request = { members : memberIds.length };
 
-				const recipients = await teamRecipients({ memberIds, organization : workflow.organization, read });
+				const { org, recipients } = await teamRecipients({ memberIds, organization : workflow.organization, read });
 
 				if( ! recipients.length ){
 
@@ -1838,6 +1848,43 @@ var drawbridge = {
 				// to redefine from here.
 				const bucket = Math.floor( Date.now() / ( 15 * 60 * 1000 ) );
 
+				// THE COPY IS OURS, not the merchant's — `step.settings.message` and
+				// `.subject` are ignored here on purpose. The whole message is "a lead
+				// arrived, go and look", so the useful part is the link, not the
+				// wording.
+				//
+				// It NAMES THE CAMPAIGN AND THE ORGANIZATION, because a recipient can
+				// be watching several of both and a subject line reading only "New
+				// lead" makes them open the mail to find out which. The campaign title
+				// is the one extra read this step makes; the org came back with the
+				// recipients.
+				const campaign = context?.campaign
+					? await read.get({ collection : 'campaign', query : { id : context.campaign } })
+					: null;
+
+				// The href is DASHBOARD-RELATIVE: a manifest must not read
+				// process.env (see lib/connections/index.js), so the deployment's base
+				// url is applied by the sender — drawbridge-sync's queue/notification.js
+				// — before it renders. Absent a campaign or lead on the context there
+				// is nothing to point at, and no button is drawn.
+				const link = ( context?.campaign && context?.lead )
+					? {
+						href : '/organizations/' + workflow.organization + '/campaigns/' + context.campaign + '/leads/' + context.lead,
+						text : 'View lead'
+					}
+					: null;
+
+				// Every part is optional and every part is dropped when it is missing,
+				// so the worst case reads 'Someone just entered.' rather than a
+				// sentence with holes in it.
+				const body = ( context?.email || 'Someone' )
+					+ ' just entered'
+					+ ( campaign?.title ? ' ' + campaign.title : '' )
+					+ ( org?.title ? ' at ' + org.title : '' )
+					+ '.';
+
+				const subject = 'New lead' + ( campaign?.title ? ' — ' + campaign.title : '' );
+
 				return {
 					message : 'Team notification queued for ' + recipients.length + ' recipient(s).',
 					request,
@@ -1849,10 +1896,11 @@ var drawbridge = {
 							// can never swallow another's mail and a later bucket is never
 							// mistaken for a duplicate of an earlier one.
 							key : 'team.notify.' + workflow.id + '.' + member.id + '.' + bucket,
-							message : interpolate( step.settings?.message, context ),
+							link,
+							message : body,
 							organization : workflow.organization,
 							send : { type : 'email', email : member.email },
-							title : interpolate( step.settings?.subject, context ),
+							title : subject,
 							workflow : workflow.id
 						}),
 						// E11000 IS THE DAMPER WORKING: this recipient has already been
@@ -2412,14 +2460,24 @@ var drawbridge = {
 
 			// To organization MEMBERS. Never suppressed — an entrant's opt-out must
 			// not silence an alert to staff — and not billed.
+			//
+			// ITS COPY IS WRITTEN, NOT ASKED FOR. This says the same thing every
+			// time — a lead arrived, here it is — so the merchant chooses who hears
+			// it, not how it reads, and the hook composes the subject, the body and
+			// the link to the lead.
+			//
+			// `message` and `subject` stay declared, optional and IGNORED: stored
+			// workflows still carry them and the api validates settings with
+			// noUnknown().strict(), so dropping the keys would 400 the next save of
+			// a workflow built before this.
 			notify : () => ({
 				hook : 'email.notify',
 				key : 'Email — Notification',
 				queue : 'notification',
 				settings : {
 					members : { of : 'string', type : 'array' },
-					message : { required : true, type : 'string' },
-					subject : { required : true, type : 'string' }
+					message : { type : 'string' },
+					subject : { type : 'string' }
 				},
 				triggers : [ 'lead.insert' ],
 				// Zero is a PRICE, and a deliberate one. Declared rather than omitted
@@ -2941,8 +2999,84 @@ var klaviyo = {
 		inbound : false,
 
 		// Nothing to set up or tear down at the vendor: the grant is the whole
-		// integration, and revoking it is auth.disconnect's job.
-		lifecycle : false,
+		// integration. What CAN rot is the grant itself, so health is the one
+		// lifecycle hook Klaviyo carries.
+		lifecycle : {
+
+			// Nothing to set up, tear down, or re-register at the vendor — the
+			// grant is the whole integration.
+			cleanup : false,
+			register : false,
+			rehydrate : false,
+
+			// KEEP THE GRANT PROVEN AND WARM. The shell mints a fresh access
+			// token before every hook run — for Klaviyo that spends the refresh
+			// token, which is the only question that reaches Klaviyo (see
+			// auth.probe) — so this body running at all proves the grant still
+			// rotates, and the daily run keeps it inside Klaviyo's 90-day idle
+			// window. A dead grant never gets here: the shell's mint throws
+			// `grant_refused` and the step runner errors the connection itself.
+			//
+			// The one call below proves the minted token is HONOURED — mint and
+			// acceptance are different facts, and /accounts is already the call
+			// the connect flow makes (auth.connect), so it needs no new scope.
+			health : async ( { connection, token }, { fetcher, read } = {} ) => {
+
+				const request = { connectionId : connection.id };
+
+				try {
+
+					await api$1( '/accounts', { fetcher, token });
+
+					return {
+						message : 'Health check passed — token minted and accepted.',
+						request,
+						response : { pingedAt : new Date() }
+					};
+
+				} catch ( error ) {
+
+					// The token we JUST minted was refused — a revoked or
+					// downgraded grant, never a transient. The write rides out
+					// on the rejection (the shell performs a thrown error's
+					// effects) because the step must still fail.
+					if( [ 401, 403 ].includes( error.status ) && read ){
+
+						const current = await read.get({ collection : 'connection', query : { id : connection.id } });
+
+						if( current ){
+
+							const others = ( current.errors || [] ).filter( ( entry ) => entry.source !== 'oauth' );
+
+							error.writes = [ {
+								collection : 'connection',
+								data : {
+									$set : {
+										errors : [
+											...others,
+											{
+												message : 'Klaviyo no longer accepts this connection. Reconnect Klaviyo to resume syncing.',
+												source : 'oauth'
+											}
+										],
+										status : 'error'
+									}
+								},
+								operation : 'update',
+								query : { id : connection.id }
+							} ];
+
+						}
+
+					}
+
+					throw error;
+
+				}
+
+			}
+
+		},
 
 		resources : {
 
@@ -3049,6 +3183,22 @@ var klaviyo = {
 
 	steps : {
 
+		connection : {
+
+			// The daily grant check — same step type and workflow shape as
+			// Shopify's, provisioned as a system workflow per connection.
+			health : {
+				check : () => ({
+					description : 'Keeps the Klaviyo grant working — spends the refresh token daily so a revoked or idle grant is reported instead of discovered by a failing sync.',
+					hook : 'lifecycle.health',
+					key : 'Klaviyo Connection Health',
+					queue : 'connection',
+					system : true
+				})
+			}
+
+		},
+
 		contacts : {
 
 			// A DECLARATION, not the work. It names the hook that does the work, and