@drawbridge/drawbridge-utils 0.0.114 → 0.0.116

package/dist/connections/index.js

@@ -378,6 +378,194 @@ var accessToken = async ({
   return next.accessToken;
 };
 
+// lib/connections/icons/attentive.js
+var attentive_default = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="500" height="500" fill="#FFD967"/>
+<path d="M239.369 127.404C260.863 122.013 284.964 132.569 295.576 152.039C321.796 201.286 347.928 250.567 374.131 299.825C380.149 311.989 381.244 326.564 376.733 339.41C371.446 355.097 358.039 367.69 342.107 372.089C326.274 376.67 308.351 372.871 295.741 362.255C288.865 356.892 284.161 349.359 280.354 341.629C261.869 306.95 243.478 272.217 225.071 237.501C214.409 218.614 187.221 212.656 169.622 225.315C168.104 227.309 164.159 226.857 164.72 223.796C176.911 202.569 189.361 181.497 201.662 160.331C205.183 154.428 208.214 148.129 212.967 143.091C219.844 135.272 229.263 129.782 239.374 127.404" fill="#1E1C1C"/>
+<path d="M166.04 261.805C180.228 259.107 195.528 261.893 207.581 269.971C218.512 277.079 226.908 288.136 230.604 300.657C234.835 314.103 233.614 329.124 227.485 341.788C220.097 356.875 205.782 368.543 189.317 372.089C173.957 375.652 157.089 372.386 144.304 363.103C132.971 355.295 124.912 342.989 121.891 329.581C118.943 316.636 120.725 302.656 127.002 290.938C134.699 275.951 149.503 264.933 166.046 261.811" fill="#1E1C1C"/>
+</svg>`;
+
+// lib/connections/attentive.js
+var attentive_default2 = {
+  auth: {
+    oauth: {
+      // NAMES of the env vars holding OUR app's client — set at registration,
+      // never before. No `headers` on the client: Attentive takes credentials
+      // as form fields, which is the runner's default.
+      client: {
+        id: "ATTENTIVE_OAUTH_CLIENT_ID",
+        secret: "ATTENTIVE_OAUTH_CLIENT_SECRET"
+      },
+      urls: {
+        authorize: "https://ui.attentivemobile.com/integrations/oauth-install",
+        redirect: "/api/connection/attentive/callback",
+        token: "https://api.attentivemobile.com/v1/authorization-codes/tokens"
+      }
+    },
+    type: "oauth"
+  },
+  // EVERYTHING A MERCHANT READS. `errors` would live in here too — the
+  // connection DOCUMENT carries its own `errors` array and is spread OVER the
+  // resolved manifest downstream, so a top-level one would never render.
+  content: {
+    // SAYS WHAT ACTUALLY HAPPENS. This used to promise that disconnecting
+    // revokes Drawbridge's access, and it cannot: Attentive documents no
+    // revocation endpoint, and their authentication page states an access
+    // token "does not expire". So the grant survives a disconnect forever
+    // unless the merchant removes the integration at Attentive, and the copy
+    // has to say so rather than let them believe otherwise.
+    confirm: "Disconnecting removes Drawbridge's stored Attentive token. Attentive does not offer a way for us to revoke it, so remove the Drawbridge integration in Attentive as well if you want its access fully withdrawn. Your subscribers stay in both Attentive and Drawbridge \u2014 neither list is deleted.",
+    description: [
+      "Attentive is where your SMS marketing lives, and this connection is becoming the way your Drawbridge contacts sync into an Attentive segment.",
+      "You authorize Drawbridge from inside Attentive and can revoke that access there at any time. Drawbridge never sees or stores your Attentive password.",
+      "Subscriber syncing is not live yet, so connecting today does nothing except choose the segment it will use when it ships."
+    ],
+    excerpt: "Sync your Drawbridge contacts into an Attentive segment.",
+    guide: [
+      "Press Connect. Drawbridge sends you to Attentive to approve access.",
+      "Sign in to Attentive if you are not already, and authorize the permissions listed.",
+      "You are returned here \u2014 choose which Attentive segment your contacts should sync into."
+    ]
+  },
+  // A contact destination, like Klaviyo and Mailchimp — a merchant could
+  // reasonably keep several up to date at once.
+  exclusive: false,
+  feature: "organization:connection:attentive",
+  fields: [
+    {
+      input: "select",
+      key: "segment",
+      label: "Attentive segment",
+      message: "Contacts your campaigns collect are synced into this segment.",
+      hook: "resources.audiences",
+      required: true
+      // No `search : false` here, and that is a first: /v2/segments takes a
+      // `name` filter (partial match, cited above), so this picker searches
+      // the ACCOUNT — Klaviyo and Mailchimp can only match the fetched page.
+    }
+  ],
+  group: "contacts",
+  // A HOOK'S VALUE IS ITS ANSWER. The consent is stored and can be revoked;
+  // nothing else is built yet, because subscriber sync has not shipped. Every
+  // false here is "not yet" rather than "never" — when the sync lands, probe
+  // and contacts.sync are the first to flip.
+  hooks: {
+    auth: {
+      // The exchange already yields the tokens, and Attentive documents no
+      // account-identity endpoint to enrich them with — Klaviyo's connect
+      // reads the account name back; this has nothing cited to read. The
+      // callback stores the tokens and skips enrichment on `unimplemented`.
+      // FALSE, NOT {}. `{}` means "supported, implemented in the repo with the
+      // dependencies", and nothing anywhere implements either of these —
+      // there is nothing for them to do. The exchange already yields the
+      // tokens and Attentive documents no account-identity endpoint to
+      // enrich them with, so connect has nothing to add; and they document
+      // no revocation endpoint at all, so disconnect has nothing to call.
+      // Recorded as a decision rather than left as an unkept promise.
+      connect: false,
+      disconnect: false,
+      probe: false,
+      scopes: false,
+      // THE ONE THING WRAPPED, and it is about the response rather than the
+      // request. Attentive's token reply carries expires_in : 900 while their
+      // auth overview says access tokens "do not expire" — and no refresh
+      // token exists to renew with. Storing that expiry would have
+      // accessToken() declaring the credential spent fifteen minutes after
+      // consent, with nothing to renew it: every connection would demand
+      // reconnecting four times an hour.
+      //
+      // The overview's answer is modelled — the expiry is dropped, so the
+      // token is treated as long-lived. Registration item 1 in the header is
+      // the live exchange that proves this right or wrong.
+      token: async (args) => {
+        const minted = await authToken(args);
+        return { ...minted, expiresIn: null };
+      }
+    },
+    commerce: false,
+    contacts: { remove: false, sync: false },
+    email: false,
+    inbound: false,
+    lifecycle: false,
+    resources: {
+      // The segments a merchant can sync into, for the picker on their
+      // connection.
+      //
+      // GET /v2/segments (cited in the header). `limit` caps at 1000 in their
+      // own spec, defaulting to 20 — low enough that leaving it unset would
+      // show a picker quietly missing most of a real account. The response's
+      // only identifier is `externalId`, so an entry without one cannot be
+      // stored and is dropped.
+      audiences: async ({ cursor, fetcher = fetch, limit = 100, search, token }) => {
+        const query = new URLSearchParams({
+          limit: String(Math.min(limit, 1e3)),
+          ...cursor && { cursor },
+          ...(search == null ? void 0 : search.value) && { name: String(search.value).trim() }
+        });
+        const response = await fetcher(
+          "https://api.attentivemobile.com/v2/segments?" + query,
+          {
+            headers: { authorization: "Bearer " + token },
+            signal: AbortSignal.timeout(15e3)
+          }
+        );
+        if (!response.ok) {
+          throw Object.assign(
+            new Error("Attentive refused the request (" + response.status + ")"),
+            { status: response.status }
+          );
+        }
+        const body = await response.json();
+        return {
+          items: ((body == null ? void 0 : body.segments) || []).filter((segment) => segment == null ? void 0 : segment.externalId).map((segment) => ({ id: segment.externalId, title: (segment == null ? void 0 : segment.name) || segment.externalId })),
+          pageInfo: {
+            endCursor: (body == null ? void 0 : body.hasMore) ? (body == null ? void 0 : body.cursor) || null : null,
+            hasNextPage: Boolean(body == null ? void 0 : body.hasMore)
+          }
+        };
+      },
+      prices: false,
+      products: false,
+      promotions: false
+    },
+    segment: false,
+    sms: false,
+    webhook: false
+  },
+  icon: attentive_default,
+  requires: [
+    "ATTENTIVE_OAUTH_CLIENT_ID",
+    "ATTENTIVE_OAUTH_CLIENT_SECRET"
+  ],
+  slug: "attentive",
+  // A consent with no segment chosen is authenticated and inert — the sync,
+  // when it ships, needs somewhere to put people.
+  status: (data2) => {
+    var _a;
+    return ((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.segment) ? data2.status : "pending";
+  },
+  // No steps: subscriber sync has not shipped, so this vendor contributes
+  // nothing to a workflow yet. An empty steps object is the honest declaration.
+  steps: {},
+  tasks: (data2) => {
+    var _a;
+    return [
+      ...((_a = data2 == null ? void 0 : data2.settings) == null ? void 0 : _a.segment) ? [] : [
+        {
+          message: "Choose which Attentive segment your contacts should sync into. Until you do, nothing is being synced.",
+          title: "Choose a segment"
+        }
+      ],
+      {
+        message: "Contact syncing to Attentive segments has not shipped yet. Nothing is being sent to Attentive right now.",
+        title: "Subscriber sync not available yet",
+        type: "warning"
+      }
+    ];
+  },
+  title: "Attentive"
+};
+
 // lib/connections/icons/drawbridge.js
 var drawbridge_default = `<svg width="500" height="500" viewBox="0 0 500 500" fill="none" xmlns="http://www.w3.org/2000/svg">
 <rect width="500" height="500" fill="#BAEC5F"/>
@@ -460,6 +648,21 @@ var field = {
   }
 };
 var connection = {
+  attentive: {
+    key: "organization:connection:attentive",
+    error: "Plan does not include Attentive connection",
+    feature: "Attentive connection"
+  },
+  // Klaviyo shipped without an entry here, which meant no plan GRANTED its
+  // key and the feature gate denied every non-admin request — a latent 403
+  // found while adding Attentive. getPlanFeature answers granted:false for a
+  // key absent from the plan's map, so a manifest feature key that appears in
+  // no plan list is a connection only admins can manage.
+  klaviyo: {
+    key: "organization:connection:klaviyo",
+    error: "Plan does not include Klaviyo connection",
+    feature: "Klaviyo connection"
+  },
   mailchimp: {
     key: "organization:connection:mailchimp",
     error: "Plan does not include Mailchimp connection",
@@ -637,6 +840,8 @@ var overage = (actionCents) => ({
 });
 var all = {
   features: (array = []) => featuresFor([
+    connection.attentive.key,
+    connection.klaviyo.key,
     connection.mailchimp.key,
     connection.sendgrid.key,
     connection.shopify.key,
@@ -1928,10 +2133,14 @@ var mailchimp_default2 = {
   // contacts.sync are the first to flip.
   hooks: {
     auth: {
-      // Implemented outside this package: storing a typed key needs no vendor
-      // call, so the api's own form handler does it.
-      connect: {},
-      disconnect: {},
+      // FALSE, NOT {}. `{}` promises an implementation living in the repo that
+      // holds the dependencies, and there is no implementation anywhere
+      // because there is nothing to implement: storing and clearing a typed
+      // key needs no vendor call, and the api's own form handler does it.
+      // Declaring `{}` made the coverage check chase a body that does not
+      // exist, and made a caller wait on an answer that never comes.
+      connect: false,
+      disconnect: false,
       probe: false,
       scopes: false,
       // Keys today. When Mailchimp's OAuth lands this becomes a wrapper that
@@ -2152,10 +2361,29 @@ var shopify_default2 = {
       // re-registers rather than answering "is this token still good", and
       // scope drift is its own hook because a token can be perfectly valid
       // while the grant is too narrow.
-      connect: {},
-      disconnect: {},
+      //
+      // connect and disconnect are FALSE rather than `{}`: there is nothing to
+      // call on either side. The install already hands the callback everything
+      // it stores, and a Shopify grant is withdrawn by UNINSTALLING the app in
+      // Shopify admin — which Drawbridge learns about from the app_uninstalled
+      // webhook rather than by asking. `{}` claimed a body implemented
+      // elsewhere; none exists, and none could.
+      connect: false,
+      disconnect: false,
       probe: false,
-      scopes: {},
+      // WHETHER THE GRANT IS STILL WIDE ENOUGH. A token can be perfectly valid
+      // and still too narrow — a deploy that adds a scope leaves every existing
+      // install short of it, and no webhook fires to say so.
+      //
+      // The comparison is the vendor's, so it belongs here. Reading WHICH
+      // scopes a store granted is not: that lives in the `shop` collection and
+      // needs a controller, which is precisely what a hook in a published
+      // package must not be handed. The caller reads the grant and passes the
+      // string; this answers what is missing from it.
+      //
+      // `shopify` is injected for the same reason it is everywhere else — this
+      // package cannot import @drawbridge/shopify, which depends on it.
+      scopes: ({ scope, shopify }) => scope ? shopify.oauth.missingScopes(scope) : null,
       // Shopify's install grant is exchanged inside its own app flow, not
       // through the shared OAuth runner.
       token: false
@@ -2209,8 +2437,65 @@ var shopify_default2 = {
       // variant and arrives with it, so there is nothing for prices to answer
       // that products does not already.
       prices: false,
-      products: {},
-      promotions: {}
+      // WHAT THE VENDOR ANSWERS, shaped for a picker. Both of these were api
+      // ROUTES — /organization/:organization/shopify/products and
+      // .../connection/:id/shopify/discounts — vendor-named urls in a service
+      // that is supposed to have none, reachable only by knowing the path.
+      // They are the same two questions every other vendor answers through
+      // resources.*, so they answer them the same way now.
+      //
+      // `shopify` is INJECTED: this package cannot import @drawbridge/shopify,
+      // which depends on it. What arrives is the SDK's pure HTTP namespaces
+      // and nothing else — no controller, no collection access. Resolving the
+      // credential is the caller's job because it is Drawbridge's job: the
+      // admin token refreshes and writes itself back, which is service work,
+      // not vendor work.
+      products: async ({ cursor, limit = 100, search, settings, shopify, sort }) => {
+        var _a, _b, _c, _d;
+        const products = await shopify.storefront.getProducts({
+          cursor,
+          domain: settings == null ? void 0 : settings.domain,
+          limit: Number(limit),
+          search: (search == null ? void 0 : search.value) || null,
+          sort,
+          storefrontAccessToken: settings == null ? void 0 : settings.storefrontAccessToken
+        });
+        return {
+          items: ((products == null ? void 0 : products.edges) || []).map((edge) => edge.node),
+          pageInfo: {
+            endCursor: ((_a = products == null ? void 0 : products.pageInfo) == null ? void 0 : _a.endCursor) || null,
+            hasNextPage: Boolean((_b = products == null ? void 0 : products.pageInfo) == null ? void 0 : _b.hasNextPage),
+            hasPreviousPage: Boolean((_c = products == null ? void 0 : products.pageInfo) == null ? void 0 : _c.hasPreviousPage),
+            startCursor: ((_d = products == null ? void 0 : products.pageInfo) == null ? void 0 : _d.startCursor) || null
+          }
+        };
+      },
+      promotions: async ({ cursor, limit = 100, search, settings, shopify }) => {
+        var _a, _b;
+        const discounts = await shopify.admin.getDiscounts({
+          adminAccessToken: settings == null ? void 0 : settings.adminAccessToken,
+          cursor,
+          domain: settings == null ? void 0 : settings.domain,
+          limit: Number(limit),
+          search: (search == null ? void 0 : search.value) || null
+        });
+        return {
+          // The GLOBAL id is what Shopify returns and the bare id is what a
+          // picker stores, which is why the tail is taken here rather than by
+          // each caller that happened to remember.
+          items: ((discounts == null ? void 0 : discounts.edges) || []).map((edge) => {
+            var _a2, _b2, _c;
+            return {
+              id: String(((_a2 = edge == null ? void 0 : edge.node) == null ? void 0 : _a2.id) || "").split("/").pop(),
+              title: (_c = (_b2 = edge == null ? void 0 : edge.node) == null ? void 0 : _b2.codeDiscount) == null ? void 0 : _c.title
+            };
+          }),
+          pageInfo: {
+            endCursor: ((_a = discounts == null ? void 0 : discounts.pageInfo) == null ? void 0 : _a.endCursor) || null,
+            hasNextPage: Boolean((_b = discounts == null ? void 0 : discounts.pageInfo) == null ? void 0 : _b.hasNextPage)
+          }
+        };
+      }
     },
     // Drawbridge posts to a merchant's own endpoint, never through a vendor.
     webhook: false
@@ -2561,10 +2846,12 @@ var webhook_default = {
   // connect generates a secret rather than proving a credential.
   hooks: {
     auth: {
-      // Minting and clearing a secret needs no vendor call, so the api's own
-      // handler does both.
-      connect: {},
-      disconnect: {},
+      // FALSE, NOT {}. There is no vendor here at all — connecting mints a
+      // secret and disconnecting clears it, both done by the api's own
+      // handler. `{}` would promise a body implemented elsewhere, and none
+      // exists or could.
+      connect: false,
+      disconnect: false,
       probe: false,
       scopes: false,
       // Nothing to mint. Connecting generates a secret; there is no vendor.
@@ -2807,6 +3094,7 @@ var stepLabels = (catalog = connections) => Object.fromEntries(
   )
 );
 var connections = Object.freeze({
+  attentive: build(attentive_default2),
   drawbridge: build(drawbridge_default2),
   hubspot: build(hubspot_default),
   klaviyo: build(klaviyo_default2),
@@ -2888,6 +3176,15 @@ var runHook = async (slug, name, args = {}) => {
 var stepQueues = (env = {}) => Object.fromEntries(
   connectionSteps(env).map((step) => [step.type, step.queue])
 );
+var stepRoutes = (env = {}) => {
+  const live = stepQueues(env);
+  return Object.freeze({
+    ...live,
+    ...Object.fromEntries(
+      Object.entries(RETIRED).filter(([, replacement]) => live[replacement]).map(([retired, replacement]) => [retired, live[replacement]])
+    )
+  });
+};
 var scopesMessage = "Shopify permissions are out of date. Open the Drawbridge app in your Shopify admin to approve the updated permissions.";
 var mergeSettings = ({ existing, incoming }) => {
   if (!existing || typeof existing !== "object") return incoming;
@@ -2995,5 +3292,6 @@ export {
   scopesMessage,
   stepLabels,
   stepQueues,
+  stepRoutes,
   tokenSettings
 };

package/dist/features.cjs

@@ -94,6 +94,21 @@ var field = {
   }
 };
 var connection = {
+  attentive: {
+    key: "organization:connection:attentive",
+    error: "Plan does not include Attentive connection",
+    feature: "Attentive connection"
+  },
+  // Klaviyo shipped without an entry here, which meant no plan GRANTED its
+  // key and the feature gate denied every non-admin request — a latent 403
+  // found while adding Attentive. getPlanFeature answers granted:false for a
+  // key absent from the plan's map, so a manifest feature key that appears in
+  // no plan list is a connection only admins can manage.
+  klaviyo: {
+    key: "organization:connection:klaviyo",
+    error: "Plan does not include Klaviyo connection",
+    feature: "Klaviyo connection"
+  },
   mailchimp: {
     key: "organization:connection:mailchimp",
     error: "Plan does not include Mailchimp connection",

package/dist/features.d.cts

@@ -68,6 +68,21 @@ const field = {
 };
 
 const connection = {
+	attentive : {
+		key : 'organization:connection:attentive',
+		error : 'Plan does not include Attentive connection',
+		feature : 'Attentive connection'
+	},
+	// Klaviyo shipped without an entry here, which meant no plan GRANTED its
+	// key and the feature gate denied every non-admin request — a latent 403
+	// found while adding Attentive. getPlanFeature answers granted:false for a
+	// key absent from the plan's map, so a manifest feature key that appears in
+	// no plan list is a connection only admins can manage.
+	klaviyo : {
+		key : 'organization:connection:klaviyo',
+		error : 'Plan does not include Klaviyo connection',
+		feature : 'Klaviyo connection'
+	},
 	mailchimp : {
 		key : 'organization:connection:mailchimp',
 		error : 'Plan does not include Mailchimp connection',

package/dist/features.d.ts

@@ -68,6 +68,21 @@ const field = {
 };
 
 const connection = {
+	attentive : {
+		key : 'organization:connection:attentive',
+		error : 'Plan does not include Attentive connection',
+		feature : 'Attentive connection'
+	},
+	// Klaviyo shipped without an entry here, which meant no plan GRANTED its
+	// key and the feature gate denied every non-admin request — a latent 403
+	// found while adding Attentive. getPlanFeature answers granted:false for a
+	// key absent from the plan's map, so a manifest feature key that appears in
+	// no plan list is a connection only admins can manage.
+	klaviyo : {
+		key : 'organization:connection:klaviyo',
+		error : 'Plan does not include Klaviyo connection',
+		feature : 'Klaviyo connection'
+	},
 	mailchimp : {
 		key : 'organization:connection:mailchimp',
 		error : 'Plan does not include Mailchimp connection',

package/dist/features.js

@@ -66,6 +66,21 @@ var field = {
   }
 };
 var connection = {
+  attentive: {
+    key: "organization:connection:attentive",
+    error: "Plan does not include Attentive connection",
+    feature: "Attentive connection"
+  },
+  // Klaviyo shipped without an entry here, which meant no plan GRANTED its
+  // key and the feature gate denied every non-admin request — a latent 403
+  // found while adding Attentive. getPlanFeature answers granted:false for a
+  // key absent from the plan's map, so a manifest feature key that appears in
+  // no plan list is a connection only admins can manage.
+  klaviyo: {
+    key: "organization:connection:klaviyo",
+    error: "Plan does not include Klaviyo connection",
+    feature: "Klaviyo connection"
+  },
   mailchimp: {
     key: "organization:connection:mailchimp",
     error: "Plan does not include Mailchimp connection",

package/dist/fields-validate.js

@@ -1,5 +1,5 @@
 // lib/phone.js
-import { parsePhoneNumberFromString, isValidPhoneNumber } from "libphonenumber-js";
+import { AsYouType, parsePhoneNumberFromString, isValidPhoneNumber } from "libphonenumber-js";
 var isValid = (value, country) => {
   if (!value) return false;
   try {

package/dist/phone.cjs

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // lib/phone.js
 var phone_exports = {};
 __export(phone_exports, {
+  detectCountry: () => detectCountry,
   isValid: () => isValid,
   toE164: () => toE164
 });
@@ -33,6 +34,16 @@ var toE164 = (value, country) => {
     return null;
   }
 };
+var detectCountry = (value) => {
+  if (!value) return null;
+  try {
+    const parser = new import_libphonenumber_js.AsYouType();
+    parser.input(String(value));
+    return parser.getCountry() || null;
+  } catch {
+    return null;
+  }
+};
 var isValid = (value, country) => {
   if (!value) return false;
   try {
@@ -43,6 +54,7 @@ var isValid = (value, country) => {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  detectCountry,
   isValid,
   toE164
 });

package/dist/phone.d.cts

@@ -1,4 +1,4 @@
-import { isValidPhoneNumber, parsePhoneNumberFromString } from 'libphonenumber-js';
+import { AsYouType, isValidPhoneNumber, parsePhoneNumberFromString } from 'libphonenumber-js';
 
 // Canonicalize a phone value to E.164 (e.g. '+15551234567'), or null if it cannot
 // be parsed. `country` (ISO 3166-1 alpha-2, e.g. 'US') is only needed for
@@ -24,6 +24,34 @@ const toE164 = ( value, country ) => {
 
 };
 
+// Resolve which country an entered number belongs to (ISO 3166-1 alpha-2), or null
+// while it is still ambiguous. Backs the country selector on phone fields, which
+// follows the number the visitor types rather than asking them to set it first.
+// libphonenumber only commits to a country once the number is COMPLETE: '+1604…'
+// stays null until the final digit because Canada and the US share the +1 calling
+// code and are told apart by area code. Callers MUST treat null as "leave the
+// current selection alone" — never as "reset it" — or every keystroke short of a
+// finished number would wipe the visitor's country.
+const detectCountry = ( value ) => {
+
+	if( ! value ) return null;
+
+	try {
+
+		const parser = new AsYouType();
+
+		parser.input( String( value ) );
+
+		return parser.getCountry() || null;
+
+	} catch {
+
+		return null;
+
+	}
+
+};
+
 // Strict validity check (wraps libphonenumber-js). Mirrors the validation
 // drawbridge-api's submission route already performs on lead phone input.
 const isValid = ( value, country ) => {
@@ -42,4 +70,4 @@ const isValid = ( value, country ) => {
 
 };
 
-export { isValid, toE164 };
+export { detectCountry, isValid, toE164 };

package/dist/phone.d.ts

@@ -1,4 +1,4 @@
-import { isValidPhoneNumber, parsePhoneNumberFromString } from 'libphonenumber-js';
+import { AsYouType, isValidPhoneNumber, parsePhoneNumberFromString } from 'libphonenumber-js';
 
 // Canonicalize a phone value to E.164 (e.g. '+15551234567'), or null if it cannot
 // be parsed. `country` (ISO 3166-1 alpha-2, e.g. 'US') is only needed for
@@ -24,6 +24,34 @@ const toE164 = ( value, country ) => {
 
 };
 
+// Resolve which country an entered number belongs to (ISO 3166-1 alpha-2), or null
+// while it is still ambiguous. Backs the country selector on phone fields, which
+// follows the number the visitor types rather than asking them to set it first.
+// libphonenumber only commits to a country once the number is COMPLETE: '+1604…'
+// stays null until the final digit because Canada and the US share the +1 calling
+// code and are told apart by area code. Callers MUST treat null as "leave the
+// current selection alone" — never as "reset it" — or every keystroke short of a
+// finished number would wipe the visitor's country.
+const detectCountry = ( value ) => {
+
+	if( ! value ) return null;
+
+	try {
+
+		const parser = new AsYouType();
+
+		parser.input( String( value ) );
+
+		return parser.getCountry() || null;
+
+	} catch {
+
+		return null;
+
+	}
+
+};
+
 // Strict validity check (wraps libphonenumber-js). Mirrors the validation
 // drawbridge-api's submission route already performs on lead phone input.
 const isValid = ( value, country ) => {
@@ -42,4 +70,4 @@ const isValid = ( value, country ) => {
 
 };
 
-export { isValid, toE164 };
+export { detectCountry, isValid, toE164 };

package/dist/phone.js

@@ -1,5 +1,5 @@
 // lib/phone.js
-import { parsePhoneNumberFromString, isValidPhoneNumber } from "libphonenumber-js";
+import { AsYouType, parsePhoneNumberFromString, isValidPhoneNumber } from "libphonenumber-js";
 var toE164 = (value, country) => {
   if (!value) return null;
   try {
@@ -9,6 +9,16 @@ var toE164 = (value, country) => {
     return null;
   }
 };
+var detectCountry = (value) => {
+  if (!value) return null;
+  try {
+    const parser = new AsYouType();
+    parser.input(String(value));
+    return parser.getCountry() || null;
+  } catch {
+    return null;
+  }
+};
 var isValid = (value, country) => {
   if (!value) return false;
   try {
@@ -18,6 +28,7 @@ var isValid = (value, country) => {
   }
 };
 export {
+  detectCountry,
   isValid,
   toE164
 };