@drawbridge/drawbridge-utils 0.0.133 → 0.0.135

package/dist/twilio.d.ts

@@ -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
+		};
+
 	}
 
 };

package/dist/twilio.js

@@ -82,28 +82,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 }
       }
@@ -140,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");
@@ -150,6 +210,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
+    };
   }
 };
 export {

package/package.json

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