@drawbridge/drawbridge-utils 0.0.133 → 0.0.135

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

@@ -107,28 +107,37 @@ var twilio = {
   // NUMBER LIFECYCLE, same transport discipline as sms above. Endpoints and
   // parameter names are Twilio's own, from the AvailablePhoneNumbers and
   // IncomingPhoneNumbers resource docs:
-  //   GET    /2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/Local.json
-  //          query: SmsEnabled, AreaCode (US/CA only), PageSize (1-1000)
+  //   GET    /2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/TollFree.json
+  //          query: SmsEnabled, Contains, PageSize (1-1000)
   //   POST   /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json
   //          body: PhoneNumber (E.164), SmsUrl, SmsMethod
   //   DELETE /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json
   // Basic auth throughout, like Messages.
-  searchNumbers: async ({ accountSid, areaCode, authToken, contains, country = "US", cursor, limit = 10, request: request2 = request }) => {
+  //
+  // TOLL-FREE, not Local, and that is a carrier-registration decision rather
+  // than an inventory one. A US local number may not send A2P SMS without full
+  // 10DLC brand-and-campaign registration; a toll-free number needs only
+  // Toll-Free Verification — one API submission per number (see
+  // submitVerification below), no TCR brand, no campaign fees. Until a
+  // verification is approved, Twilio blocks the number's US-bound messages
+  // outright — which is why a purchased number starts `pending` and the send
+  // path refuses anything but `verified`.
+  searchNumbers: async ({ accountSid, authToken, contains, country = "US", cursor, limit = 10, request: request2 = request }) => {
     if (!accountSid || !authToken) throw new Error("Twilio credentials missing \u2014 accountSid, authToken");
     const page = Number(cursor) || 0;
     const result = await request2({
       method: "GET",
-      url: "https://api.twilio.com/2010-04-01/Accounts/" + accountSid + "/AvailablePhoneNumbers/" + country + "/Local.json",
+      url: "https://api.twilio.com/2010-04-01/Accounts/" + accountSid + "/AvailablePhoneNumbers/" + country + "/TollFree.json",
       headers: {
         "Authorization": "Basic " + Buffer.from(accountSid + ":" + authToken).toString("base64")
       },
       query: {
         SmsEnabled: true,
         PageSize: limit,
-        ...areaCode && { AreaCode: areaCode },
         // `Contains` is the vendor's matching-pattern filter — digits
-        // match anywhere in the number, so one search box serves "my
-        // area code" and "ends in 7777" alike.
+        // match anywhere in the number, so one search box serves "an 888
+        // prefix" and "ends in 7777" alike. (AreaCode is a Local-only
+        // filter and went with Local.json.)
         ...contains && { Contains: contains },
         ...page && { Page: page }
       }
@@ -165,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");
@@ -175,6 +235,84 @@ var twilio = {
         "Authorization": "Basic " + Buffer.from(accountSid + ":" + authToken).toString("base64")
       }
     });
+  },
+  // TOLL-FREE VERIFICATION — the carrier registration that lets a purchased
+  // number actually deliver. From the Tollfree Verification resource docs
+  // (messaging.twilio.com, docs/messaging/api/tollfree-verification-resource):
+  //   POST   /v1/Tollfree/Verifications
+  //          required: BusinessName, BusinessWebsite, NotificationEmail,
+  //          UseCaseCategories (array), UseCaseSummary,
+  //          ProductionMessageSample, OptInImageUrls (array), OptInType,
+  //          MessageVolume, TollfreePhoneNumberSid (PN…)
+  //   GET    /v1/Tollfree/Verifications/{Sid}
+  //          status: PENDING_REVIEW | IN_REVIEW | TWILIO_APPROVED |
+  //          TWILIO_REJECTED, with rejection_reason beside a rejection.
+  // Basic auth, form-encoded, like everything above. There is no status
+  // callback on this resource — the caller polls the fetch.
+  //
+  // THE END BUSINESS'S DETAILS, never the platform's. Twilio rejects ISV
+  // submissions carrying the ISV's own identity (Toll-Free Verification for
+  // ISVs, support.twilio.com) — so businessName, website and email here are
+  // the merchant's, collected at purchase.
+  //
+  // The use-case fields are PLATFORM facts and live here beside the message
+  // composition for the same reason it does: how Drawbridge collects opt-in
+  // (its own hosted entry forms) and what its messages look like are
+  // properties of sending through Drawbridge, not of any one merchant.
+  submitVerification: async ({
+    accountSid,
+    authToken,
+    businessName,
+    email,
+    numberSid,
+    optInImage,
+    request: request2 = request,
+    volume,
+    website
+  }) => {
+    const missing = Object.entries({ accountSid, authToken, businessName, email, numberSid, optInImage, website }).filter(([, value]) => !value).map(([name]) => name);
+    if (missing.length) throw new Error("Toll-free verification submission missing \u2014 " + missing.join(", "));
+    const body = new URLSearchParams();
+    body.append("BusinessName", businessName);
+    body.append("BusinessWebsite", website);
+    body.append("NotificationEmail", email);
+    body.append("UseCaseCategories", "MARKETING");
+    body.append("UseCaseSummary", "Prize-draw entry confirmations, winner notifications and campaign updates to consumers who opted in on this business's Drawbridge-hosted entry form.");
+    body.append("ProductionMessageSample", businessName + "\nThanks for entering! We'll text you here about your entry.\nReply STOP to opt out");
+    body.append("OptInImageUrls", optInImage);
+    body.append("OptInType", "WEB_FORM");
+    body.append("MessageVolume", volume || "1,000");
+    body.append("TollfreePhoneNumberSid", numberSid);
+    const result = await request2({
+      method: "POST",
+      type: "form",
+      url: "https://messaging.twilio.com/v1/Tollfree/Verifications",
+      headers: {
+        "Authorization": "Basic " + Buffer.from(accountSid + ":" + authToken).toString("base64")
+      },
+      body
+    });
+    return {
+      sid: result == null ? void 0 : result.sid,
+      status: result == null ? void 0 : result.status
+    };
+  },
+  fetchVerification: 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 verification fetch needs the verification sid");
+    const result = await request2({
+      method: "GET",
+      url: "https://messaging.twilio.com/v1/Tollfree/Verifications/" + sid,
+      headers: {
+        "Authorization": "Basic " + Buffer.from(accountSid + ":" + authToken).toString("base64")
+      }
+    });
+    return {
+      // TWILIO_APPROVED → verified, TWILIO_REJECTED → rejected, both
+      // review states → pending.
+      outcome: (result == null ? void 0 : result.status) === "TWILIO_APPROVED" ? "approved" : (result == null ? void 0 : result.status) === "TWILIO_REJECTED" ? "rejected" : "pending",
+      reason: (result == null ? void 0 : result.rejection_reason) || null
+    };
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/twilio.d.cts

@@ -70,14 +70,23 @@ const twilio = {
 	// NUMBER LIFECYCLE, same transport discipline as sms above. Endpoints and
 	// parameter names are Twilio's own, from the AvailablePhoneNumbers and
 	// IncomingPhoneNumbers resource docs:
-	//   GET    /2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/Local.json
-	//          query: SmsEnabled, AreaCode (US/CA only), PageSize (1-1000)
+	//   GET    /2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/TollFree.json
+	//          query: SmsEnabled, Contains, PageSize (1-1000)
 	//   POST   /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json
 	//          body: PhoneNumber (E.164), SmsUrl, SmsMethod
 	//   DELETE /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json
 	// Basic auth throughout, like Messages.
+	//
+	// TOLL-FREE, not Local, and that is a carrier-registration decision rather
+	// than an inventory one. A US local number may not send A2P SMS without full
+	// 10DLC brand-and-campaign registration; a toll-free number needs only
+	// Toll-Free Verification — one API submission per number (see
+	// submitVerification below), no TCR brand, no campaign fees. Until a
+	// verification is approved, Twilio blocks the number's US-bound messages
+	// outright — which is why a purchased number starts `pending` and the send
+	// path refuses anything but `verified`.
 
-	searchNumbers : async ({ accountSid, areaCode, authToken, contains, country = 'US', cursor, limit = 10, request: request$1 = request }) => {
+	searchNumbers : async ({ accountSid, authToken, contains, country = 'US', cursor, limit = 10, request: request$1 = request }) => {
 
 		if( ! accountSid || ! authToken ) throw new Error( 'Twilio credentials missing — accountSid, authToken' );
 
@@ -93,17 +102,17 @@ const twilio = {
 
 		const result = await request$1({
 			method : 'GET',
-			url : 'https://api.twilio.com/2010-04-01/Accounts/' + accountSid + '/AvailablePhoneNumbers/' + country + '/Local.json',
+			url : 'https://api.twilio.com/2010-04-01/Accounts/' + accountSid + '/AvailablePhoneNumbers/' + country + '/TollFree.json',
 			headers : {
 				'Authorization' : 'Basic ' + Buffer.from( accountSid + ':' + authToken ).toString( 'base64' )
 			},
 			query : {
 				SmsEnabled : true,
 				PageSize : limit,
-				...( areaCode && { AreaCode : areaCode } ),
 				// `Contains` is the vendor's matching-pattern filter — digits
-				// match anywhere in the number, so one search box serves "my
-				// area code" and "ends in 7777" alike.
+				// match anywhere in the number, so one search box serves "an 888
+				// prefix" and "ends in 7777" alike. (AreaCode is a Local-only
+				// filter and went with Local.json.)
 				...( contains && { Contains : contains } ),
 				...( page && { Page : page } )
 			}
@@ -150,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' );
@@ -163,6 +239,111 @@ const twilio = {
 			}
 		});
 
+	},
+
+	// TOLL-FREE VERIFICATION — the carrier registration that lets a purchased
+	// number actually deliver. From the Tollfree Verification resource docs
+	// (messaging.twilio.com, docs/messaging/api/tollfree-verification-resource):
+	//   POST   /v1/Tollfree/Verifications
+	//          required: BusinessName, BusinessWebsite, NotificationEmail,
+	//          UseCaseCategories (array), UseCaseSummary,
+	//          ProductionMessageSample, OptInImageUrls (array), OptInType,
+	//          MessageVolume, TollfreePhoneNumberSid (PN…)
+	//   GET    /v1/Tollfree/Verifications/{Sid}
+	//          status: PENDING_REVIEW | IN_REVIEW | TWILIO_APPROVED |
+	//          TWILIO_REJECTED, with rejection_reason beside a rejection.
+	// Basic auth, form-encoded, like everything above. There is no status
+	// callback on this resource — the caller polls the fetch.
+	//
+	// THE END BUSINESS'S DETAILS, never the platform's. Twilio rejects ISV
+	// submissions carrying the ISV's own identity (Toll-Free Verification for
+	// ISVs, support.twilio.com) — so businessName, website and email here are
+	// the merchant's, collected at purchase.
+	//
+	// The use-case fields are PLATFORM facts and live here beside the message
+	// composition for the same reason it does: how Drawbridge collects opt-in
+	// (its own hosted entry forms) and what its messages look like are
+	// properties of sending through Drawbridge, not of any one merchant.
+	submitVerification : async ({
+		accountSid,
+		authToken,
+		businessName,
+		email,
+		numberSid,
+		optInImage,
+		request: request$1 = request,
+		volume,
+		website
+	}) => {
+
+		const missing = Object.entries({ accountSid, authToken, businessName, email, numberSid, optInImage, website })
+			.filter( ( [ , value ] ) => ! value )
+			.map( ( [ name ] ) => name );
+
+		if( missing.length ) throw new Error( 'Toll-free verification submission missing — ' + missing.join( ', ' ) );
+
+		// URLSearchParams rather than an object: UseCaseCategories and
+		// OptInImageUrls are array parameters, which Twilio takes as REPEATED
+		// form keys — an object body would comma-join them into one value.
+		const body = new URLSearchParams();
+
+		body.append( 'BusinessName', businessName );
+		body.append( 'BusinessWebsite', website );
+		body.append( 'NotificationEmail', email );
+		body.append( 'UseCaseCategories', 'MARKETING' );
+		body.append( 'UseCaseSummary', 'Prize-draw entry confirmations, winner notifications and campaign updates to consumers who opted in on this business\'s Drawbridge-hosted entry form.' );
+		// Mirrors the sms() composition above — newline-separated, brand first,
+		// opt-out line appended — so the reviewed sample is the sent shape.
+		body.append( 'ProductionMessageSample', businessName + '\nThanks for entering! We\'ll text you here about your entry.\nReply STOP to opt out' );
+		body.append( 'OptInImageUrls', optInImage );
+		// The entry form is a web form; the phone field is beside the consent
+		// language on the merchant's campaign page.
+		body.append( 'OptInType', 'WEB_FORM' );
+		body.append( 'MessageVolume', volume || '1,000' );
+		body.append( 'TollfreePhoneNumberSid', numberSid );
+
+		const result = await request$1({
+			method : 'POST',
+			type : 'form',
+			url : 'https://messaging.twilio.com/v1/Tollfree/Verifications',
+			headers : {
+				'Authorization' : 'Basic ' + Buffer.from( accountSid + ':' + authToken ).toString( 'base64' )
+			},
+			body
+		});
+
+		return {
+			sid : result?.sid,
+			status : result?.status
+		};
+
+	},
+
+	fetchVerification : 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 verification fetch needs the verification sid' );
+
+		const result = await request$1({
+			method : 'GET',
+			url : 'https://messaging.twilio.com/v1/Tollfree/Verifications/' + sid,
+			headers : {
+				'Authorization' : 'Basic ' + Buffer.from( accountSid + ':' + authToken ).toString( 'base64' )
+			}
+		});
+
+		// The caller-facing shape is ours; the vendor's vocabulary stays here.
+		return {
+			// TWILIO_APPROVED → verified, TWILIO_REJECTED → rejected, both
+			// review states → pending.
+			outcome : result?.status === 'TWILIO_APPROVED'
+				? 'approved'
+				: result?.status === 'TWILIO_REJECTED'
+					? 'rejected'
+					: 'pending',
+			reason : result?.rejection_reason || null
+		};
+
 	}
 
 };