@drawbridge/drawbridge-utils 0.0.108 → 0.0.110

package/dist/connections/index.cjs

@@ -26,6 +26,7 @@ __export(connections_exports, {
   INPUTS: () => INPUTS,
   OAUTH_FIELDS: () => OAUTH_FIELDS,
   OUTCOMES: () => OUTCOMES,
+  accessToken: () => accessToken,
   availableConnections: () => availableConnections,
   build: () => build,
   connectFields: () => connectFields,
@@ -34,6 +35,7 @@ __export(connections_exports, {
   consentUrl: () => consentUrl,
   exchange: () => exchange,
   hookSupport: () => hookSupport,
+  isStale: () => isStale,
   mergeSettings: () => mergeSettings,
   pkcePair: () => pkcePair,
   projectConnection: () => projectConnection,
@@ -44,7 +46,8 @@ __export(connections_exports, {
   resolveConnection: () => resolveConnection,
   runHook: () => runHook,
   scopesMessage: () => scopesMessage,
-  stepQueues: () => stepQueues
+  stepQueues: () => stepQueues,
+  tokenSettings: () => tokenSettings
 });
 module.exports = __toCommonJS(connections_exports);
 
@@ -250,6 +253,56 @@ var refresh = async ({ clientId, clientSecret, descriptor, fetcher = fetch, refr
   };
 };
 
+// lib/connections/token.js
+var SKEW_SECONDS = 120;
+var isStale = (settings, now = Date.now()) => {
+  if (!(settings == null ? void 0 : settings.expiresAt)) return false;
+  return new Date(settings.expiresAt).getTime() - SKEW_SECONDS * 1e3 <= now;
+};
+var tokenSettings = ({ existing = {}, now = Date.now(), tokens }) => ({
+  accessToken: tokens.accessToken,
+  // A vendor that does not rotate its refresh token returns none on a refresh
+  // (Klaviyo). Keeping the existing one is what makes the NEXT refresh work —
+  // dropping it invalidates the grant one call later, nowhere near the cause.
+  ...(tokens.refreshToken || existing.refreshToken) && {
+    refreshToken: tokens.refreshToken || existing.refreshToken
+  },
+  // Absent when the vendor issues non-expiring tokens, and absent is meaningful
+  // — isStale reads it as "nothing to refresh toward".
+  ...tokens.expiresIn && {
+    expiresAt: new Date(now + tokens.expiresIn * 1e3).toISOString()
+  },
+  ...tokens.scope && { scope: tokens.scope }
+});
+var accessToken = async ({
+  clientId,
+  clientSecret,
+  fetcher,
+  force = false,
+  manifest,
+  now = Date.now(),
+  save,
+  settings
+} = {}) => {
+  if (!(settings == null ? void 0 : settings.accessToken) && !(settings == null ? void 0 : settings.refreshToken)) {
+    throw new Error("This connection holds no credential, so there is no token to use");
+  }
+  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.");
+  }
+  const minted = await refresh({
+    clientId,
+    clientSecret,
+    descriptor: manifest.auth.oauth,
+    ...fetcher && { fetcher },
+    refreshToken: settings.refreshToken
+  });
+  const next = tokenSettings({ existing: settings, now, tokens: minted });
+  if (save) await save(next);
+  return next.accessToken;
+};
+
 // lib/connections/icons/klaviyo.js
 var klaviyo_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="white"/>
@@ -257,6 +310,26 @@ var klaviyo_default = `<svg width="500" height="500" viewBox="0 0 500 500" fill=
 </svg>`;
 
 // lib/connections/klaviyo.js
+var REVISION = "2026-07-15";
+var api = async (path, { fetcher = fetch, token }) => {
+  const response = await fetcher("https://a.klaviyo.com/api" + path, {
+    headers: {
+      // Bearer, not Klaviyo-API-Key — that header is for private keys, and
+      // sending it with an OAuth token fails in a way that reads like a bad
+      // token rather than a bad scheme.
+      authorization: "Bearer " + token,
+      revision: REVISION
+    },
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!response.ok) {
+    throw Object.assign(
+      new Error("Klaviyo refused the request (" + response.status + ")"),
+      { status: response.status }
+    );
+  }
+  return response.json();
+};
 var klaviyo_default2 = {
   // OAuth 2.1, and PKCE is REQUIRED rather than recommended: Klaviyo refuses an
   // exchange without a code_verifier matching the challenge the consent
@@ -269,7 +342,17 @@ var klaviyo_default2 = {
   // Google product wants it.
   auth: {
     oauth: {
-      authorize: "https://a.klaviyo.com/oauth/authorize",
+      // TWO DIFFERENT HOSTS, and swapping them fails in opposite directions.
+      //
+      // authorize is a page a HUMAN loads, and it lives on www. Pointing it at
+      // a.klaviyo.com -- their API host -- sends the merchant somewhere that
+      // never renders a consent screen, so the journey stalls with no error
+      // anybody can see.
+      //
+      // token is a server call and must stay on a.klaviyo.com: Klaviyo began
+      // blocking OAuth token traffic through www on 2025-03-31, so the mirror
+      // image of this mistake breaks the exchange instead of the consent.
+      authorize: "https://www.klaviyo.com/oauth/authorize",
       // NAMES the env vars holding OUR application's client. One identity,
       // every merchant — the token is the merchant's and arrives from their
       // own consent, which is what stops one organization reading another's
@@ -285,6 +368,11 @@ var klaviyo_default2 = {
       // it is a fact about someone else's records rather than a string this
       // code computes. Deriving one from a provider key produced
       // redirect_uri_mismatch on a connection nobody had touched.
+      // Klaviyo drops a refresh token after 90 days of NON-USE. The vendor
+      // never mentions this at runtime — you discover it when a refresh fails
+      // on a connection nobody touched — so it is declared, and it is why
+      // auth.probe has to run on a schedule rather than only before a call.
+      idleExpiry: 90 * 24 * 60 * 60,
       redirect: "/api/connection/klaviyo/callback",
       // Space separated. accounts:read is required by Klaviyo on every app
       // and must stay in the list; the rest are what a contact sync needs.
@@ -316,7 +404,78 @@ var klaviyo_default2 = {
       label: "Klaviyo account"
     }
   ],
+  // The three auth hooks, all pure HTTP against Klaviyo — which is why they
+  // live here rather than in sync. A vendor's own protocol belongs beside the
+  // vendor.
+  hooks: {
+    // Turn a fresh grant into settings worth showing. Without this the card
+    // renders an empty "Klaviyo account" field, because the merchant is never
+    // asked which account they connected — the consent already decided it and
+    // asking again would be a question we can answer ourselves.
+    "auth.connect": async ({ fetcher, tokens }) => {
+      var _a, _b, _c;
+      const body = await api("/accounts", { fetcher, token: tokens.accessToken });
+      const account = (_a = body == null ? void 0 : body.data) == null ? void 0 : _a[0];
+      return {
+        account: ((_c = (_b = account == null ? void 0 : account.attributes) == null ? void 0 : _b.contact_information) == null ? void 0 : _c.organization_name) || (account == null ? void 0 : account.id) || null,
+        accountId: (account == null ? void 0 : account.id) || null
+      };
+    },
+    // Revoke at KLAVIYO, not just locally. Forgetting our copy leaves the
+    // grant live in the merchant's account, so a disconnect that looks
+    // complete here still shows Drawbridge with access over there.
+    //
+    // Basic auth with our client, exactly like the token exchange — the token
+    // being revoked is the subject, not the credential.
+    "auth.disconnect": async ({ clientId, clientSecret, fetcher = fetch, settings }) => {
+      const token = (settings == null ? void 0 : settings.refreshToken) || (settings == null ? void 0 : settings.accessToken);
+      if (!token) return { revoked: false };
+      const response = await fetcher("https://a.klaviyo.com/oauth/revoke", {
+        body: new URLSearchParams({
+          token,
+          token_type_hint: (settings == null ? void 0 : settings.refreshToken) ? "refresh_token" : "access_token"
+        }),
+        headers: {
+          authorization: "Basic " + Buffer.from(clientId + ":" + clientSecret).toString("base64"),
+          "content-type": "application/x-www-form-urlencoded"
+        },
+        method: "POST",
+        signal: AbortSignal.timeout(15e3)
+      });
+      return { revoked: response.ok };
+    },
+    // THE MINT IS THE PROBE. Asking "is this token still good" by inspecting
+    // what we stored answers the wrong question — a grant revoked inside
+    // Klaviyo still looks perfect in our database. Spending the refresh token
+    // is the only thing that asks Klaviyo.
+    //
+    // It also keeps the grant warm: Klaviyo expires a refresh token after 90
+    // days of NON-USE, so a connection nobody touches dies silently without
+    // this running.
+    "auth.probe": async ({ clientId, clientSecret, fetcher, manifest, settings }) => {
+      const token = await accessToken({
+        clientId,
+        clientSecret,
+        fetcher,
+        // Mint even if the stored token still looks good — a probe that
+        // short-circuits never reaches Klaviyo and reports healthy on a
+        // grant revoked an hour ago.
+        force: true,
+        manifest,
+        settings
+      });
+      return { ok: Boolean(token) };
+    }
+  },
   icon: klaviyo_default,
+  // A grant with no list chosen is authenticated and useless. The list cannot
+  // be part of the consent flow — enumerating lists needs the token the consent
+  // returns — so it is always a second step, and the card must say so rather
+  // than showing Active over nothing.
+  incomplete: (data) => {
+    var _a;
+    return ((_a = data == null ? void 0 : data.settings) == null ? void 0 : _a.list) ? null : "Choose which Klaviyo list your contacts should sync into.";
+  },
   label: "klaviyo",
   requires: [
     "KLAVIYO_OAUTH_CLIENT_ID",
@@ -352,6 +511,16 @@ var klaviyo_default2 = {
     "lifecycle.register": false,
     "lifecycle.rehydrate": false
   },
+  tasks: () => [
+    // Mailchimp carries the same warning, deliberately worded the same way. A
+    // merchant who connects either one and is told nothing reasonably assumes
+    // contacts are flowing, and finds out weeks later that they are not.
+    {
+      message: "Contact syncing to Klaviyo lists has not shipped yet. Connecting stores your authorization so it is ready, but nothing is being sent to Klaviyo right now.",
+      title: "List sync not available yet",
+      type: "warning"
+    }
+  ],
   title: "Klaviyo"
 };
 
@@ -403,6 +572,15 @@ var mailchimp_default2 = {
     }
   ],
   icon: mailchimp_default,
+  // A key with no audience chosen is authenticated and inert. Mailchimp also
+  // needs its merge fields created on that audience before any Drawbridge total
+  // can be written to a member — unlike Klaviyo, its custom fields are not
+  // schemaless — so the audience must be picked before lifecycle.register has
+  // anything to register against.
+  incomplete: (data) => {
+    var _a;
+    return ((_a = data == null ? void 0 : data.settings) == null ? void 0 : _a.audience) ? null : "Choose which Mailchimp audience your contacts should sync into.";
+  },
   label: "mailchimp",
   // Uniform surface, honest answers. A key is stored and can be removed; nothing
   // else is built yet, because audience sync has not shipped. Every false here
@@ -532,16 +710,21 @@ var shopify_default2 = {
     }
   ],
   group: "ecommerce",
+  // The install is the whole configuration — Shopify hands back the shop and
+  // there is nothing further to choose. `shop` absent means the install did not
+  // finish, which is a credential problem rather than a setup one, so the
+  // stored status already says so.
+  incomplete: () => null,
   // verify and event lean entirely on the shared HMAC helper — Shopify's scheme
   // is exactly the shape it covers, so there is nothing vendor-specific to
   // write for either. receive is the one hook that genuinely differs by
-  // action: /events buffers whatever arrives with the shop domain stamped on;
+  // channel: /events buffers whatever arrives with the shop domain stamped on;
   // /compliance enforces the topic allowlist above, because answering one late
   // is a legal deadline rather than a retry.
   hooks: {
     "inbound.event": (args) => readEventHeader({ ...args, descriptor: inbound }),
-    "inbound.receive": ({ action, event, headers, payload }) => {
-      if (action === "compliance" && !COMPLIANCE_TOPICS.has(event)) {
+    "inbound.receive": ({ channel, event, headers, payload }) => {
+      if (channel === "compliance" && !COMPLIANCE_TOPICS.has(event)) {
         throw Object.assign(new Error("Unrecognized compliance topic: " + event), { status: 401 });
       }
       return {
@@ -549,7 +732,7 @@ var shopify_default2 = {
         // own GDPR shape. The app-level event stream does not; that domain
         // lives only in the header, so it is stamped on here rather than left
         // for drawbridge-sync to reach into headers nobody hands it.
-        data: action === "compliance" ? payload : { ...payload, shop_domain: headers[inbound.headers.shop] || null },
+        data: channel === "compliance" ? payload : { ...payload, shop_domain: headers[inbound.headers.shop] || null },
         provider: { id: headers[inbound.headers.id] || null }
       };
     },
@@ -731,6 +914,9 @@ var webhook_default = {
   // It is the one card that reads wrong — our logo among vendor logos — and it
   // wants a mark of its own when there is one.
   icon: drawbridge_default,
+  // The destination url is supplied per step, not per connection, so there is
+  // nothing to finish here — generating the secret IS connecting.
+  incomplete: () => null,
   label: "webhook",
   // Gated on the encryption secret: without it the signing secret could not be
   // stored safely, so the connection must not be offered at all.
@@ -838,6 +1024,11 @@ var build = (manifest) => {
         throw new Error(manifest.slug + " is oauth and must declare auth.oauth." + field);
       }
     }
+    if (manifest.auth.oauth.redirect !== "/api/connection/" + manifest.slug + "/callback") {
+      throw new Error(
+        manifest.slug + " declares auth.oauth.redirect " + manifest.auth.oauth.redirect + " but the only callback route is /api/connection/" + manifest.slug + "/callback"
+      );
+    }
   }
   if (((_d = manifest.supports) == null ? void 0 : _d["inbound.event"]) && !((_f = (_e = manifest.inbound) == null ? void 0 : _e.headers) == null ? void 0 : _f.event)) {
     throw new Error(manifest.slug + " supports inbound.event but declares no inbound.headers.event");
@@ -845,6 +1036,9 @@ var build = (manifest) => {
   if (((_g = manifest.supports) == null ? void 0 : _g["inbound.verify"]) && !((_i = (_h = manifest.inbound) == null ? void 0 : _h.headers) == null ? void 0 : _i.signature)) {
     throw new Error(manifest.slug + " supports inbound.verify but declares no inbound.headers.signature");
   }
+  if (typeof (manifest == null ? void 0 : manifest.incomplete) !== "function") {
+    throw new Error(manifest.slug + " must declare incomplete( data ) \u2014 return null when the connection is usable, or the reason it is not");
+  }
   if (!Array.isArray(manifest == null ? void 0 : manifest.setup) || !manifest.setup.length) {
     throw new Error(manifest.slug + " needs a setup guide \u2014 an array of steps for its page");
   }
@@ -994,6 +1188,9 @@ var publicConnectionKeys = Object.freeze([
   "group",
   "id",
   "image",
+  // The reason a connected vendor still is not usable — a Klaviyo grant with no
+  // list chosen. Public because the card that shows Pending has to say why.
+  "incomplete",
   "label",
   "setup",
   "settings",
@@ -1036,6 +1233,7 @@ var resolveConnection = (item, data) => {
   INPUTS,
   OAUTH_FIELDS,
   OUTCOMES,
+  accessToken,
   availableConnections,
   build,
   connectFields,
@@ -1044,6 +1242,7 @@ var resolveConnection = (item, data) => {
   consentUrl,
   exchange,
   hookSupport,
+  isStale,
   mergeSettings,
   pkcePair,
   projectConnection,
@@ -1054,5 +1253,6 @@ var resolveConnection = (item, data) => {
   resolveConnection,
   runHook,
   scopesMessage,
-  stepQueues
+  stepQueues,
+  tokenSettings
 });