@drawbridge/drawbridge-utils 0.0.107 → 0.0.109

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);
 
@@ -76,14 +79,49 @@ var HOOKS = Object.freeze({
     "cleanup"
   ]),
   // Receiving from the vendor.
+  //
+  // Split across TWO SERVICES, and the split is the point. `verify` and `event`
+  // and `receive` run in drawbridge-webhooks against the vendor's open
+  // connection, where the budget is whatever that vendor's timeout is —
+  // Shopify's is about five seconds, and missing it means they retry and the
+  // delivery is buffered twice. `process` runs in drawbridge-sync off the
+  // buffer, where it can take as long as it needs and retry without the vendor
+  // ever knowing.
+  //
+  // One hook spanning that seam would hide it, and the thing it hides is the
+  // one most likely to bite: slow work written on the receiving side turns
+  // into duplicate deliveries.
   inbound: Object.freeze([
-    // Prove the request came from the vendor. Signature schemes differ per
-    // vendor, which is exactly why this is a hook and not one shared function.
+    // Prove the request came from the vendor, AND return the payload it
+    // carries. One hook rather than two because for some vendors they are
+    // genuinely one operation: a JWT-bodied webhook (Kinde) cannot be decoded
+    // into anything trustworthy without verifying it first, and a decode that
+    // runs before the signature check is exactly the bug this shape prevents.
+    //
+    // So the raw bytes stop here. Everything downstream receives the payload
+    // this returned, which means nothing downstream can act on unverified
+    // data even by mistake.
+    //
+    // It is also where a request gets refused for any other reason — an event
+    // outside the allowlist, a connection in the wrong state. Anything that
+    // can reject belongs here, so the route holds no rules of its own.
     "verify",
-    // Name the event, from wherever this vendor puts it.
-    "topic",
-    // Do the work the event implies.
-    "handle"
+    // Name the event, from wherever this vendor puts it. A header for
+    // Shopify, the route itself for Twilio, a claim in the payload for a
+    // JWT-bodied vendor.
+    "event",
+    // What to buffer and what to answer RIGHT NOW, while the vendor waits.
+    // Thin by obligation. Most vendors only shape a buffer doc here; one that
+    // must reply with content (Twilio answers HELP inline with TwiML, which
+    // carriers require) returns that too.
+    "receive",
+    // Do the work the event implies. Runs in drawbridge-sync, off the buffer.
+    //
+    // DECLARED here, IMPLEMENTED there — the same split as the step handlers,
+    // and for the same reason: this half needs controllers, queues and vendor
+    // SDKs, and putting those behind a published package makes every consumer
+    // carry them. The declaration is what proves the implementation exists.
+    "process"
   ]),
   // Vendor data a campaign draws on. Named for what every store platform has,
   // not for what Shopify calls it: Shopify says discounts, Stripe says coupons
@@ -215,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"/>
@@ -222,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
@@ -250,6 +358,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.
@@ -281,7 +394,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",
@@ -309,13 +493,24 @@ var klaviyo_default2 = {
     "catalog.prices": false,
     "catalog.products": false,
     "catalog.promotions": false,
-    "inbound.handle": false,
-    "inbound.topic": false,
+    "inbound.event": false,
+    "inbound.process": false,
+    "inbound.receive": false,
     "inbound.verify": false,
     "lifecycle.cleanup": false,
     "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"
 };
 
@@ -367,6 +562,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
@@ -380,8 +584,9 @@ var mailchimp_default2 = {
     "catalog.prices": false,
     "catalog.products": false,
     "catalog.promotions": false,
-    "inbound.handle": false,
-    "inbound.topic": false,
+    "inbound.event": false,
+    "inbound.process": false,
+    "inbound.receive": false,
     "inbound.verify": false,
     "lifecycle.cleanup": false,
     "lifecycle.register": false,
@@ -415,7 +620,42 @@ var shopify_default = `<svg width="500" height="500" viewBox="0 0 500 500" fill=
 <path d="M258.993 193.019L249.103 230.052C249.103 230.052 238.079 225.023 225 225.85C205.833 227.059 205.628 239.171 205.824 242.21C206.865 258.756 250.376 262.381 252.821 301.171C254.745 331.688 236.656 352.574 210.592 354.21C179.313 356.19 162.089 337.711 162.089 337.711L168.716 309.472C168.716 309.472 186.052 322.569 199.921 321.686C208.993 321.119 212.228 313.738 211.903 308.514C210.536 286.921 175.102 288.185 172.862 252.695C170.985 222.811 190.57 192.554 233.803 189.821C250.46 188.762 258.993 193.028 258.993 193.028" fill="white"/>
 </svg>`;
 
+// lib/connections/inbound.js
+var import_node_crypto2 = require("crypto");
+var verifySignature = ({ body, descriptor, headers }) => {
+  const provided = headers[descriptor.headers.signature];
+  if (!provided) {
+    throw Object.assign(new Error("Missing webhook signature"), { status: 401 });
+  }
+  const digest = (0, import_node_crypto2.createHmac)(descriptor.signature.algorithm, process.env[descriptor.signature.secret]).update(body).digest(descriptor.signature.encoding);
+  const digestBuffer = Buffer.from(digest, descriptor.signature.encoding);
+  const providedBuffer = Buffer.from(provided, descriptor.signature.encoding);
+  if (digestBuffer.length !== providedBuffer.length || !(0, import_node_crypto2.timingSafeEqual)(digestBuffer, providedBuffer)) {
+    throw Object.assign(new Error("Invalid webhook signature"), { status: 401 });
+  }
+  return JSON.parse(body.toString());
+};
+var readEventHeader = ({ descriptor, headers }) => headers[descriptor.headers.event];
+
 // lib/connections/shopify.js
+var inbound = {
+  headers: {
+    event: "x-shopify-topic",
+    id: "x-shopify-webhook-id",
+    shop: "x-shopify-shop-domain",
+    signature: "x-shopify-hmac-sha256"
+  },
+  signature: {
+    algorithm: "sha256",
+    encoding: "base64",
+    secret: "SHOPIFY_API_SECRET"
+  }
+};
+var COMPLIANCE_TOPICS = /* @__PURE__ */ new Set([
+  "customers/data_request",
+  "customers/redact",
+  "shop/redact"
+]);
 var shopify_default2 = {
   // INSTALL, not oauth. The grant is an OAuth grant, but the merchant never
   // sees a consent screen we sent them to -- they start at the App Store, and
@@ -460,30 +700,36 @@ var shopify_default2 = {
     }
   ],
   group: "ecommerce",
-  // WHERE THIS VENDOR PUTS THINGS ON AN INBOUND REQUEST. Header names are facts
-  // about someone else's product, so they belong beside the rest of the vendor
-  // rather than as string literals in a route — which is where they were, and
-  // is why a second inbound vendor meant a second route file.
-  //
-  // `signature` describes an HMAC scheme the shared verifier can run: hash the
-  // raw body with the named secret and compare, constant-time, against the
-  // header. Vendors whose scheme is not that shape — Stripe signs a timestamped
-  // payload — declare no signature block and implement inbound.verify instead.
-  // That is why verify is a hook and not config.
-  inbound: {
-    headers: {
-      id: "x-shopify-webhook-id",
-      shop: "x-shopify-shop-domain",
-      signature: "x-shopify-hmac-sha256",
-      topic: "x-shopify-topic"
+  // 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
+  // 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": ({ channel, event, headers, payload }) => {
+      if (channel === "compliance" && !COMPLIANCE_TOPICS.has(event)) {
+        throw Object.assign(new Error("Unrecognized compliance topic: " + event), { status: 401 });
+      }
+      return {
+        // Compliance payloads already carry shop_domain in the body — Shopify's
+        // 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: channel === "compliance" ? payload : { ...payload, shop_domain: headers[inbound.headers.shop] || null },
+        provider: { id: headers[inbound.headers.id] || null }
+      };
     },
-    signature: {
-      algorithm: "sha256",
-      encoding: "base64",
-      secret: "SHOPIFY_API_SECRET"
-    }
+    "inbound.verify": (args) => verifySignature({ ...args, descriptor: inbound })
   },
   icon: shopify_default,
+  inbound,
   label: "shopify",
   // A pre-launch integration: it only surfaces once the App Store listing
   // exists and the app is fully configured. Requiring all four means it can
@@ -512,8 +758,9 @@ var shopify_default2 = {
     "catalog.prices": false,
     "catalog.products": true,
     "catalog.promotions": true,
-    "inbound.handle": true,
-    "inbound.topic": true,
+    "inbound.event": true,
+    "inbound.process": true,
+    "inbound.receive": true,
     "inbound.verify": true,
     "lifecycle.cleanup": true,
     "lifecycle.register": true,
@@ -657,6 +904,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.
@@ -673,8 +923,9 @@ var webhook_default = {
     "catalog.prices": false,
     "catalog.products": false,
     "catalog.promotions": false,
-    "inbound.handle": false,
-    "inbound.topic": false,
+    "inbound.event": false,
+    "inbound.process": false,
+    "inbound.receive": false,
     "inbound.verify": false,
     "lifecycle.cleanup": false,
     "lifecycle.register": false,
@@ -763,13 +1014,21 @@ 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.topic"]) && !((_f = (_e = manifest.inbound) == null ? void 0 : _e.headers) == null ? void 0 : _f.topic)) {
-    throw new Error(manifest.slug + " supports inbound.topic but declares no inbound.headers.topic");
+  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");
   }
   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");
   }
@@ -880,7 +1139,7 @@ var runHook = async (slug, name, args = {}) => {
   try {
     return { outcome: OUTCOMES.answered, result: await hook(args) };
   } catch (error) {
-    return { error: (error == null ? void 0 : error.message) || "failed", outcome: OUTCOMES.failed };
+    return { error: (error == null ? void 0 : error.message) || "failed", outcome: OUTCOMES.failed, status: (error == null ? void 0 : error.status) || null };
   }
 };
 var stepQueues = (env = {}) => Object.fromEntries(
@@ -919,6 +1178,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",
@@ -946,7 +1208,7 @@ var projectConnection = (record) => {
 var resolveConnection = (item, data) => {
   if (!item) return item;
   return Object.fromEntries(
-    Object.entries(item).filter(([key]) => !["auth", "enabled", "fields", "inbound", "requires", "steps", "supports"].includes(key)).map(([key, value]) => [
+    Object.entries(item).filter(([key]) => !["auth", "enabled", "fields", "hooks", "inbound", "requires", "steps", "supports"].includes(key)).map(([key, value]) => [
       key,
       typeof value === "function" ? value(data) : value
     ])
@@ -961,6 +1223,7 @@ var resolveConnection = (item, data) => {
   INPUTS,
   OAUTH_FIELDS,
   OUTCOMES,
+  accessToken,
   availableConnections,
   build,
   connectFields,
@@ -969,6 +1232,7 @@ var resolveConnection = (item, data) => {
   consentUrl,
   exchange,
   hookSupport,
+  isStale,
   mergeSettings,
   pkcePair,
   projectConnection,
@@ -979,5 +1243,6 @@ var resolveConnection = (item, data) => {
   resolveConnection,
   runHook,
   scopesMessage,
-  stepQueues
+  stepQueues,
+  tokenSettings
 });