@drawbridge/drawbridge-utils 0.0.134 → 0.0.135

package/dist/connections/index.cjs

@@ -464,8 +464,14 @@ var authToken = async ({
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) {
-    throw new Error(
-      renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+    throw Object.assign(
+      new Error(
+        renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+      ),
+      {
+        status: response.status,
+        ...renewing && { code: "grant_refused" }
+      }
     );
   }
   if (!renewing && !body.access_token) throw new Error("The vendor returned no access token");
@@ -521,7 +527,10 @@ var accessToken = async ({
   }
   if (!force && !isStale(settings, now)) return settings.accessToken;
   if (!settings.refreshToken) {
-    throw new Error("This connection has expired and cannot be renewed automatically. Reconnect it.");
+    throw Object.assign(
+      new Error("This connection has expired and cannot be renewed automatically. Reconnect it."),
+      { code: "grant_refused" }
+    );
   }
   const minted = await manifest.hooks.auth.token({
     clientId,
@@ -2735,8 +2744,62 @@ var klaviyo_default2 = {
     sms: false,
     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: connection2, token }, { fetcher, read } = {}) => {
+        const request2 = { connectionId: connection2.id };
+        try {
+          await api2("/accounts", { fetcher, token });
+          return {
+            message: "Health check passed \u2014 token minted and accepted.",
+            request: request2,
+            response: { pingedAt: /* @__PURE__ */ new Date() }
+          };
+        } catch (error) {
+          if ([401, 403].includes(error.status) && read) {
+            const current = await read.get({ collection: "connection", query: { id: connection2.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: connection2.id }
+              }];
+            }
+          }
+          throw error;
+        }
+      }
+    },
     resources: {
       // The lists a merchant can sync into, for the picker on their
       // connection.
@@ -2812,6 +2875,19 @@ var klaviyo_default2 = {
     return ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.list) ? data2.status : "pending";
   },
   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 \u2014 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
       // says where that hook's values belong. Nested like the hooks, and the

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' }
+		);
 
 	}
 
@@ -2941,8 +2945,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 +3129,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' }
+		);
 
 	}
 
@@ -2941,8 +2945,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 +3129,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.js

@@ -390,8 +390,14 @@ var authToken = async ({
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) {
-    throw new Error(
-      renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+    throw Object.assign(
+      new Error(
+        renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+      ),
+      {
+        status: response.status,
+        ...renewing && { code: "grant_refused" }
+      }
     );
   }
   if (!renewing && !body.access_token) throw new Error("The vendor returned no access token");
@@ -447,7 +453,10 @@ var accessToken = async ({
   }
   if (!force && !isStale(settings, now)) return settings.accessToken;
   if (!settings.refreshToken) {
-    throw new Error("This connection has expired and cannot be renewed automatically. Reconnect it.");
+    throw Object.assign(
+      new Error("This connection has expired and cannot be renewed automatically. Reconnect it."),
+      { code: "grant_refused" }
+    );
   }
   const minted = await manifest.hooks.auth.token({
     clientId,
@@ -2661,8 +2670,62 @@ var klaviyo_default2 = {
     sms: false,
     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: connection2, token }, { fetcher, read } = {}) => {
+        const request2 = { connectionId: connection2.id };
+        try {
+          await api2("/accounts", { fetcher, token });
+          return {
+            message: "Health check passed \u2014 token minted and accepted.",
+            request: request2,
+            response: { pingedAt: /* @__PURE__ */ new Date() }
+          };
+        } catch (error) {
+          if ([401, 403].includes(error.status) && read) {
+            const current = await read.get({ collection: "connection", query: { id: connection2.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: connection2.id }
+              }];
+            }
+          }
+          throw error;
+        }
+      }
+    },
     resources: {
       // The lists a merchant can sync into, for the picker on their
       // connection.
@@ -2738,6 +2801,19 @@ var klaviyo_default2 = {
     return ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.list) ? data2.status : "pending";
   },
   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 \u2014 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
       // says where that hook's values belong. Nested like the hooks, and the

package/dist/connections/oauth.cjs

@@ -94,8 +94,14 @@ var authToken = async ({
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) {
-    throw new Error(
-      renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+    throw Object.assign(
+      new Error(
+        renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+      ),
+      {
+        status: response.status,
+        ...renewing && { code: "grant_refused" }
+      }
     );
   }
   if (!renewing && !body.access_token) throw new Error("The vendor returned no access token");

package/dist/connections/oauth.d.cts

@@ -173,9 +173,20 @@ const authToken = async ({
 		// The two paths fail differently for the merchant: a refused exchange is
 		// "try connecting again", a refused refresh is "reconnect this connection",
 		// and collapsing them sends somebody to the wrong screen.
-		throw new Error( renewing
-			? 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection'
-			: 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' )
+		//
+		// `code` marks the refused REFRESH machine-readably — the health-check
+		// shell errors the connection on it rather than retrying a dead grant
+		// into the log forever. Only the renewing branch: a refused exchange is
+		// a connect-flow failure with a person watching.
+		throw Object.assign(
+			new Error( renewing
+				? 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection'
+				: 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' )
+			),
+			{
+				status : response.status,
+				...( renewing && { code : 'grant_refused' })
+			}
 		);
 
 	}

package/dist/connections/oauth.d.ts

@@ -173,9 +173,20 @@ const authToken = async ({
 		// The two paths fail differently for the merchant: a refused exchange is
 		// "try connecting again", a refused refresh is "reconnect this connection",
 		// and collapsing them sends somebody to the wrong screen.
-		throw new Error( renewing
-			? 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection'
-			: 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' )
+		//
+		// `code` marks the refused REFRESH machine-readably — the health-check
+		// shell errors the connection on it rather than retrying a dead grant
+		// into the log forever. Only the renewing branch: a refused exchange is
+		// a connect-flow failure with a person watching.
+		throw Object.assign(
+			new Error( renewing
+				? 'The vendor refused the refresh token (' + response.status + ') — reconnect the connection'
+				: 'The vendor refused the exchange (' + response.status + ')' + ( body?.error ? ': ' + body.error : '' )
+			),
+			{
+				status : response.status,
+				...( renewing && { code : 'grant_refused' })
+			}
 		);
 
 	}

package/dist/connections/oauth.js

@@ -69,8 +69,14 @@ var authToken = async ({
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) {
-    throw new Error(
-      renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+    throw Object.assign(
+      new Error(
+        renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+      ),
+      {
+        status: response.status,
+        ...renewing && { code: "grant_refused" }
+      }
     );
   }
   if (!renewing && !body.access_token) throw new Error("The vendor returned no access token");

package/dist/providers.cjs

@@ -370,8 +370,14 @@ var authToken = async ({
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) {
-    throw new Error(
-      renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+    throw Object.assign(
+      new Error(
+        renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+      ),
+      {
+        status: response.status,
+        ...renewing && { code: "grant_refused" }
+      }
     );
   }
   if (!renewing && !body.access_token) throw new Error("The vendor returned no access token");
@@ -427,7 +433,10 @@ var accessToken = async ({
   }
   if (!force && !isStale(settings, now)) return settings.accessToken;
   if (!settings.refreshToken) {
-    throw new Error("This connection has expired and cannot be renewed automatically. Reconnect it.");
+    throw Object.assign(
+      new Error("This connection has expired and cannot be renewed automatically. Reconnect it."),
+      { code: "grant_refused" }
+    );
   }
   const minted = await manifest.hooks.auth.token({
     clientId,
@@ -2641,8 +2650,62 @@ var klaviyo_default2 = {
     sms: false,
     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: connection2, token }, { fetcher, read } = {}) => {
+        const request2 = { connectionId: connection2.id };
+        try {
+          await api2("/accounts", { fetcher, token });
+          return {
+            message: "Health check passed \u2014 token minted and accepted.",
+            request: request2,
+            response: { pingedAt: /* @__PURE__ */ new Date() }
+          };
+        } catch (error) {
+          if ([401, 403].includes(error.status) && read) {
+            const current = await read.get({ collection: "connection", query: { id: connection2.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: connection2.id }
+              }];
+            }
+          }
+          throw error;
+        }
+      }
+    },
     resources: {
       // The lists a merchant can sync into, for the picker on their
       // connection.
@@ -2718,6 +2781,19 @@ var klaviyo_default2 = {
     return ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.list) ? data2.status : "pending";
   },
   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 \u2014 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
       // says where that hook's values belong. Nested like the hooks, and the

package/dist/providers.js

@@ -326,8 +326,14 @@ var authToken = async ({
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) {
-    throw new Error(
-      renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+    throw Object.assign(
+      new Error(
+        renewing ? "The vendor refused the refresh token (" + response.status + ") \u2014 reconnect the connection" : "The vendor refused the exchange (" + response.status + ")" + ((body == null ? void 0 : body.error) ? ": " + body.error : "")
+      ),
+      {
+        status: response.status,
+        ...renewing && { code: "grant_refused" }
+      }
     );
   }
   if (!renewing && !body.access_token) throw new Error("The vendor returned no access token");
@@ -383,7 +389,10 @@ var accessToken = async ({
   }
   if (!force && !isStale(settings, now)) return settings.accessToken;
   if (!settings.refreshToken) {
-    throw new Error("This connection has expired and cannot be renewed automatically. Reconnect it.");
+    throw Object.assign(
+      new Error("This connection has expired and cannot be renewed automatically. Reconnect it."),
+      { code: "grant_refused" }
+    );
   }
   const minted = await manifest.hooks.auth.token({
     clientId,
@@ -2597,8 +2606,62 @@ var klaviyo_default2 = {
     sms: false,
     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: connection2, token }, { fetcher, read } = {}) => {
+        const request2 = { connectionId: connection2.id };
+        try {
+          await api2("/accounts", { fetcher, token });
+          return {
+            message: "Health check passed \u2014 token minted and accepted.",
+            request: request2,
+            response: { pingedAt: /* @__PURE__ */ new Date() }
+          };
+        } catch (error) {
+          if ([401, 403].includes(error.status) && read) {
+            const current = await read.get({ collection: "connection", query: { id: connection2.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: connection2.id }
+              }];
+            }
+          }
+          throw error;
+        }
+      }
+    },
     resources: {
       // The lists a merchant can sync into, for the picker on their
       // connection.
@@ -2674,6 +2737,19 @@ var klaviyo_default2 = {
     return ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.list) ? data2.status : "pending";
   },
   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 \u2014 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
       // says where that hook's values belong. Nested like the hooks, and the

package/dist/twilio.cjs

@@ -174,6 +174,57 @@ var twilio = {
       sid: result == null ? void 0 : result.sid
     };
   },
+  // THE NUMBER AS TWILIO HOLDS IT NOW. Same IncomingPhoneNumber resource the
+  // purchase and release above use (api.twilio.com 2010-04-01, GET
+  // /IncomingPhoneNumbers/{sid}.json) — a 404 means the number is no longer
+  // on the account, which the health sweep must distinguish from a transient,
+  // so it is answered as { gone : true } rather than thrown.
+  numberConfig: async ({ accountSid, authToken, request: request2 = request, sid }) => {
+    if (!accountSid || !authToken) throw new Error("Twilio credentials missing \u2014 accountSid, authToken");
+    if (!sid) throw new Error("Twilio config read needs the IncomingPhoneNumber sid");
+    let result;
+    try {
+      result = await request2({
+        method: "GET",
+        url: "https://api.twilio.com/2010-04-01/Accounts/" + accountSid + "/IncomingPhoneNumbers/" + sid + ".json",
+        headers: {
+          "Authorization": "Basic " + Buffer.from(accountSid + ":" + authToken).toString("base64")
+        }
+      });
+    } catch (error) {
+      if ((error == null ? void 0 : error.status) === 404) return { gone: true };
+      throw error;
+    }
+    return {
+      gone: false,
+      number: result == null ? void 0 : result.phone_number,
+      smsMethod: result == null ? void 0 : result.sms_method,
+      smsUrl: result == null ? void 0 : result.sms_url,
+      status: result == null ? void 0 : result.status
+    };
+  },
+  // RE-POINT AN OWNED NUMBER'S INBOUND WEBHOOK — POST on the same resource,
+  // the exact fields purchase sets. The health sweep's repair arm.
+  updateNumber: async ({ accountSid, authToken, request: request2 = request, sid, smsUrl }) => {
+    if (!accountSid || !authToken) throw new Error("Twilio credentials missing \u2014 accountSid, authToken");
+    if (!sid) throw new Error("Twilio update needs the IncomingPhoneNumber sid");
+    if (!smsUrl) throw new Error("Twilio update needs the smsUrl to point the number at");
+    const result = await request2({
+      method: "POST",
+      type: "form",
+      url: "https://api.twilio.com/2010-04-01/Accounts/" + accountSid + "/IncomingPhoneNumbers/" + sid + ".json",
+      headers: {
+        "Authorization": "Basic " + Buffer.from(accountSid + ":" + authToken).toString("base64")
+      },
+      body: {
+        SmsUrl: smsUrl,
+        SmsMethod: "POST"
+      }
+    });
+    return {
+      smsUrl: result == null ? void 0 : result.sms_url
+    };
+  },
   releaseNumber: async ({ accountSid, authToken, request: request2 = request, sid }) => {
     if (!accountSid || !authToken) throw new Error("Twilio credentials missing \u2014 accountSid, authToken");
     if (!sid) throw new Error("Twilio release needs the IncomingPhoneNumber sid");

package/dist/twilio.d.cts

@@ -159,6 +159,73 @@ const twilio = {
 
 	},
 
+	// THE NUMBER AS TWILIO HOLDS IT NOW. Same IncomingPhoneNumber resource the
+	// purchase and release above use (api.twilio.com 2010-04-01, GET
+	// /IncomingPhoneNumbers/{sid}.json) — a 404 means the number is no longer
+	// on the account, which the health sweep must distinguish from a transient,
+	// so it is answered as { gone : true } rather than thrown.
+	numberConfig : async ({ accountSid, authToken, request: request$1 = request, sid }) => {
+
+		if( ! accountSid || ! authToken ) throw new Error( 'Twilio credentials missing — accountSid, authToken' );
+		if( ! sid ) throw new Error( 'Twilio config read needs the IncomingPhoneNumber sid' );
+
+		let result;
+
+		try {
+
+			result = await request$1({
+				method : 'GET',
+				url : 'https://api.twilio.com/2010-04-01/Accounts/' + accountSid + '/IncomingPhoneNumbers/' + sid + '.json',
+				headers : {
+					'Authorization' : 'Basic ' + Buffer.from( accountSid + ':' + authToken ).toString( 'base64' )
+				}
+			});
+
+		} catch ( error ) {
+
+			if( error?.status === 404 ) return { gone : true };
+
+			throw error;
+
+		}
+
+		return {
+			gone : false,
+			number : result?.phone_number,
+			smsMethod : result?.sms_method,
+			smsUrl : result?.sms_url,
+			status : result?.status
+		};
+
+	},
+
+	// RE-POINT AN OWNED NUMBER'S INBOUND WEBHOOK — POST on the same resource,
+	// the exact fields purchase sets. The health sweep's repair arm.
+	updateNumber : async ({ accountSid, authToken, request: request$1 = request, sid, smsUrl }) => {
+
+		if( ! accountSid || ! authToken ) throw new Error( 'Twilio credentials missing — accountSid, authToken' );
+		if( ! sid ) throw new Error( 'Twilio update needs the IncomingPhoneNumber sid' );
+		if( ! smsUrl ) throw new Error( 'Twilio update needs the smsUrl to point the number at' );
+
+		const result = await request$1({
+			method : 'POST',
+			type : 'form',
+			url : 'https://api.twilio.com/2010-04-01/Accounts/' + accountSid + '/IncomingPhoneNumbers/' + sid + '.json',
+			headers : {
+				'Authorization' : 'Basic ' + Buffer.from( accountSid + ':' + authToken ).toString( 'base64' )
+			},
+			body : {
+				SmsUrl : smsUrl,
+				SmsMethod : 'POST'
+			}
+		});
+
+		return {
+			smsUrl : result?.sms_url
+		};
+
+	},
+
 	releaseNumber : async ({ accountSid, authToken, request: request$1 = request, sid }) => {
 
 		if( ! accountSid || ! authToken ) throw new Error( 'Twilio credentials missing — accountSid, authToken' );

package/dist/twilio.d.ts

@@ -159,6 +159,73 @@ const twilio = {
 
 	},
 
+	// THE NUMBER AS TWILIO HOLDS IT NOW. Same IncomingPhoneNumber resource the
+	// purchase and release above use (api.twilio.com 2010-04-01, GET
+	// /IncomingPhoneNumbers/{sid}.json) — a 404 means the number is no longer
+	// on the account, which the health sweep must distinguish from a transient,
+	// so it is answered as { gone : true } rather than thrown.
+	numberConfig : async ({ accountSid, authToken, request: request$1 = request, sid }) => {
+
+		if( ! accountSid || ! authToken ) throw new Error( 'Twilio credentials missing — accountSid, authToken' );
+		if( ! sid ) throw new Error( 'Twilio config read needs the IncomingPhoneNumber sid' );
+
+		let result;
+
+		try {
+
+			result = await request$1({
+				method : 'GET',
+				url : 'https://api.twilio.com/2010-04-01/Accounts/' + accountSid + '/IncomingPhoneNumbers/' + sid + '.json',
+				headers : {
+					'Authorization' : 'Basic ' + Buffer.from( accountSid + ':' + authToken ).toString( 'base64' )
+				}
+			});
+
+		} catch ( error ) {
+
+			if( error?.status === 404 ) return { gone : true };
+
+			throw error;
+
+		}
+
+		return {
+			gone : false,
+			number : result?.phone_number,
+			smsMethod : result?.sms_method,
+			smsUrl : result?.sms_url,
+			status : result?.status
+		};
+
+	},
+
+	// RE-POINT AN OWNED NUMBER'S INBOUND WEBHOOK — POST on the same resource,
+	// the exact fields purchase sets. The health sweep's repair arm.
+	updateNumber : async ({ accountSid, authToken, request: request$1 = request, sid, smsUrl }) => {
+
+		if( ! accountSid || ! authToken ) throw new Error( 'Twilio credentials missing — accountSid, authToken' );
+		if( ! sid ) throw new Error( 'Twilio update needs the IncomingPhoneNumber sid' );
+		if( ! smsUrl ) throw new Error( 'Twilio update needs the smsUrl to point the number at' );
+
+		const result = await request$1({
+			method : 'POST',
+			type : 'form',
+			url : 'https://api.twilio.com/2010-04-01/Accounts/' + accountSid + '/IncomingPhoneNumbers/' + sid + '.json',
+			headers : {
+				'Authorization' : 'Basic ' + Buffer.from( accountSid + ':' + authToken ).toString( 'base64' )
+			},
+			body : {
+				SmsUrl : smsUrl,
+				SmsMethod : 'POST'
+			}
+		});
+
+		return {
+			smsUrl : result?.sms_url
+		};
+
+	},
+
 	releaseNumber : async ({ accountSid, authToken, request: request$1 = request, sid }) => {
 
 		if( ! accountSid || ! authToken ) throw new Error( 'Twilio credentials missing — accountSid, authToken' );

package/dist/twilio.js

@@ -149,6 +149,57 @@ var twilio = {
       sid: result == null ? void 0 : result.sid
     };
   },
+  // THE NUMBER AS TWILIO HOLDS IT NOW. Same IncomingPhoneNumber resource the
+  // purchase and release above use (api.twilio.com 2010-04-01, GET
+  // /IncomingPhoneNumbers/{sid}.json) — a 404 means the number is no longer
+  // on the account, which the health sweep must distinguish from a transient,
+  // so it is answered as { gone : true } rather than thrown.
+  numberConfig: async ({ accountSid, authToken, request: request2 = request, sid }) => {
+    if (!accountSid || !authToken) throw new Error("Twilio credentials missing \u2014 accountSid, authToken");
+    if (!sid) throw new Error("Twilio config read needs the IncomingPhoneNumber sid");
+    let result;
+    try {
+      result = await request2({
+        method: "GET",
+        url: "https://api.twilio.com/2010-04-01/Accounts/" + accountSid + "/IncomingPhoneNumbers/" + sid + ".json",
+        headers: {
+          "Authorization": "Basic " + Buffer.from(accountSid + ":" + authToken).toString("base64")
+        }
+      });
+    } catch (error) {
+      if ((error == null ? void 0 : error.status) === 404) return { gone: true };
+      throw error;
+    }
+    return {
+      gone: false,
+      number: result == null ? void 0 : result.phone_number,
+      smsMethod: result == null ? void 0 : result.sms_method,
+      smsUrl: result == null ? void 0 : result.sms_url,
+      status: result == null ? void 0 : result.status
+    };
+  },
+  // RE-POINT AN OWNED NUMBER'S INBOUND WEBHOOK — POST on the same resource,
+  // the exact fields purchase sets. The health sweep's repair arm.
+  updateNumber: async ({ accountSid, authToken, request: request2 = request, sid, smsUrl }) => {
+    if (!accountSid || !authToken) throw new Error("Twilio credentials missing \u2014 accountSid, authToken");
+    if (!sid) throw new Error("Twilio update needs the IncomingPhoneNumber sid");
+    if (!smsUrl) throw new Error("Twilio update needs the smsUrl to point the number at");
+    const result = await request2({
+      method: "POST",
+      type: "form",
+      url: "https://api.twilio.com/2010-04-01/Accounts/" + accountSid + "/IncomingPhoneNumbers/" + sid + ".json",
+      headers: {
+        "Authorization": "Basic " + Buffer.from(accountSid + ":" + authToken).toString("base64")
+      },
+      body: {
+        SmsUrl: smsUrl,
+        SmsMethod: "POST"
+      }
+    });
+    return {
+      smsUrl: result == null ? void 0 : result.sms_url
+    };
+  },
   releaseNumber: async ({ accountSid, authToken, request: request2 = request, sid }) => {
     if (!accountSid || !authToken) throw new Error("Twilio credentials missing \u2014 accountSid, authToken");
     if (!sid) throw new Error("Twilio release needs the IncomingPhoneNumber sid");

package/package.json

@@ -215,5 +215,5 @@
     "test": ". \"$HOME/.nvm/nvm.sh\" && nvm use && node --test"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.134"
+  "version": "0.0.135"
 }