@drawbridge/drawbridge-utils 0.0.136 → 0.0.139

package/dist/connections/index.cjs

@@ -639,6 +639,9 @@ var attentive_default2 = {
   },
   // A contact destination, like Klaviyo and Mailchimp — a merchant could
   // reasonably keep several up to date at once.
+  // No vendor-facing event identities — declared empty so the contract stays
+  // explicit: a vendor that gains one adds it here, never as a side channel.
+  events: {},
   exclusive: false,
   feature: "organization:connection:attentive",
   fields: [
@@ -1819,6 +1822,9 @@ var drawbridge_default2 = {
       "Nothing to do. These steps are available in every workflow builder."
     ]
   },
+  // No vendor-facing event identities — declared empty so the contract stays
+  // explicit: a vendor that gains one adds it here, never as a side channel.
+  events: {},
   exclusive: false,
   fields: [],
   group: "developer",
@@ -2603,6 +2609,9 @@ var klaviyo_default2 = {
   // current — so the exclusivity that once applied when these were SENDERS is
   // deliberately gone. That was removed once already; declaring it out loud is
   // what stops it coming back by inference.
+  // No vendor-facing event identities — declared empty so the contract stays
+  // explicit: a vendor that gains one adds it here, never as a side channel.
+  events: {},
   exclusive: false,
   feature: "organization:connection:klaviyo",
   fields: [
@@ -3079,6 +3088,9 @@ var mailchimp_default2 = {
   // picking two providers to send the same mail was meaningless. As contact
   // syncs they are destinations, and a merchant could reasonably keep several
   // up to date, so the exclusivity is gone.
+  // No vendor-facing event identities — declared empty so the contract stays
+  // explicit: a vendor that gains one adds it here, never as a side channel.
+  events: {},
   exclusive: false,
   feature: "organization:connection:mailchimp",
   fields: [
@@ -3354,6 +3366,22 @@ var toCanonicalEmail = (value) => {
   return local + "@" + domain;
 };
 
+// lib/slugify.js
+var import_slugify = __toESM(require("slugify"), 1);
+var slugify = (value, nochars = false) => {
+  const remove = nochars ? /[-?*+~.()'"!:@#^_{}\[\];,/\\]/g : /[?*+~.()'"!:@#^_{}\[\];,/\\]/g;
+  const replacement = nochars ? "" : "-";
+  return (0, import_slugify.default)(
+    value,
+    {
+      remove,
+      replacement,
+      lower: true,
+      trim: true
+    }
+  );
+};
+
 // lib/connections/providers/shopify.js
 var toLine = ({
   price,
@@ -3389,6 +3417,7 @@ var attributeLineItems = (lineItems = []) => lineItems.reduce(
   { attrMap: {}, attributedGross: 0, attributedLines: [] }
 );
 var generateDiscountCode = (0, import_nanoid2.customAlphabet)("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ", 8);
+var ORDER_EVENT_HANDLE = slugify("drawbridge-orders");
 var REFRESH_TOKEN_FRESHNESS_BUFFER_MS = 5 * 24 * 60 * 60 * 1e3;
 var OAUTH_ERROR_SOURCE = "oauth";
 var OAUTH_GRANT_REVOKED_CODES = ["application_cannot_be_found", "invalid_grant"];
@@ -3446,7 +3475,7 @@ var shopify_default2 = {
     guide: [
       "Open the Drawbridge listing on the Shopify App Store.",
       "Install the app on the store you want to connect. It opens in Shopify admin and stays there.",
-      "Choose a plan when Shopify asks. The connection shows Pending until you do, then Active.",
+      "Approve the Drawbridge plan when prompted \u2014 during install, or from the connection page here. The connection shows Pending until you do, then Active.",
       "Come back here \u2014 the connections list updates on its own once the install lands."
     ],
     // Names where the link GOES rather than what it does: installing happens on
@@ -3460,6 +3489,29 @@ var shopify_default2 = {
   // ONE STORE PER ORGANIZATION. Two Shopify stores on one org would give every
   // attributed order two possible sources.
   exclusive: true,
+  // VENDOR-FACING EVENT IDENTITY, published so readers outside this package
+  // (drawbridge-sync's usage queue, an operator checking the Dev Dashboard)
+  // see the same handle the order hook mints into transactions and enqueues.
+  events: {
+    order: {
+      handle: ORDER_EVENT_HANDLE,
+      // THE SUBSCRIPTION THE APP MINTS FOR ITSELF (Billing API, not the
+      // managed-pricing meter system): a $0 recurring line plus this usage
+      // line, approved by the org owner at Shopify's confirmation screen.
+      // `terms` is the merchant-visible consent copy; "up to" because the
+      // actual rate is plan-derived (conversionRate) and must never exceed
+      // what was approved. cappedAmount bounds one 30-day cycle's usage
+      // charges — a record beyond it errors until the merchant raises it.
+      // ponytail: $1,000 cap ≈ $66k attributed revenue/cycle at 1.5%; raise
+      // via a re-approved subscription when a merchant outgrows it.
+      pricing: {
+        cappedAmount: 1e3,
+        currency: "usd",
+        name: "Drawbridge Orders",
+        terms: "Up to 1.5% of revenue from orders attributed to Drawbridge campaigns"
+      }
+    }
+  },
   feature: "organization:connection:shopify",
   fields: [
     {
@@ -3645,7 +3697,7 @@ var shopify_default2 = {
       // for one purchase. The hook used to loop for this itself; describing
       // the writes moved the retry to the queue, with the same guarantee.
       order: async ({ connection: connection2, context }, { logger: logger2, mintId, read } = {}) => {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         const {
           advertisement,
           created_at: createdAt,
@@ -3887,8 +3939,26 @@ var shopify_default2 = {
             });
           }
         }
-        const enqueues = (org == null ? void 0 : org.billingProvider) === "shopify" && fee > 0 && ((_f = connection2 == null ? void 0 : connection2.source) == null ? void 0 : _f.id) && !backfill ? [{
+        const billable = (org == null ? void 0 : org.billingProvider) === "shopify" && fee > 0 && !backfill;
+        if (billable && !((_f = connection2 == null ? void 0 : connection2.source) == null ? void 0 : _f.id)) {
+          (_g = logger2 == null ? void 0 : logger2.error) == null ? void 0 : _g.call(logger2, new Error(
+            "shopify.usage.billing.skipped on order " + orderId + ": " + Math.round(fee * 100) + " cents not billed \u2014 connection " + (connection2 == null ? void 0 : connection2.id) + " has no source.id"
+          ), {
+            extra: {
+              connectionId: connection2 == null ? void 0 : connection2.id,
+              fee,
+              orderDocId,
+              orderId: String(orderId)
+            }
+          });
+        }
+        const enqueues = billable && ((_h = connection2 == null ? void 0 : connection2.source) == null ? void 0 : _h.id) ? [{
           data: {
+            // The meter handle travels WITH the job so the sender can
+            // verify it against the transaction prefix and refuse a
+            // drifted pair — idempotency keys are permanent, so a
+            // mistraceable event can never be resent under its own key.
+            handle: ORDER_EVENT_HANDLE,
             idempotencyKey: String(orderId),
             orderDocId,
             orderId: String(orderId),
@@ -3898,7 +3968,7 @@ var shopify_default2 = {
             // here — the event handle plus the order id — and sent as the
             // event's `reference`. queue/usage.js stamps the same id onto
             // the order as billed.transaction.
-            transaction: "drawbridge-orders." + orderId,
+            transaction: ORDER_EVENT_HANDLE + "." + orderId,
             value: Math.round(fee * 100)
           },
           name: "billing",
@@ -4041,7 +4111,8 @@ var shopify_default2 = {
       // access token still works, reconciles the scopes the store granted
       // against the ones the app now needs, and queues a webhook
       // reconciliation.
-      health: async ({ connection: connection2, workflow }, { adminToken, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {}) => {
+      health: async ({ connection: connection2, workflow }, { adminToken, logger: logger2, read, reconcileScopes, resolveSettings, rotateToken, shopify } = {}) => {
+        var _a, _b;
         const request2 = {
           connectionId: workflow.connection,
           organizationId: workflow.organization,
@@ -4060,7 +4131,50 @@ var shopify_default2 = {
           }
           await shopify.oauth.ping({ adminAccessToken, domain: connection2.shop });
           const scopesMissing = await reconcileScopes({ shop: connection2.shop });
+          const writes = [];
+          let source = connection2.source || null;
+          let sourceRepaired = false;
+          let metered = (source == null ? void 0 : source.metered) ?? null;
+          let shopCurrency = null;
+          let billingProbeFailed = false;
+          try {
+            if (!(source == null ? void 0 : source.id)) {
+              const shopData = await shopify.oauth.getShop({ adminAccessToken, shop: connection2.shop });
+              source = {
+                domain: shopData.myshopifyDomain,
+                id: String(shopData.id),
+                label: shopData.name
+              };
+              shopCurrency = String(shopData.currency || "").toLowerCase() || null;
+              sourceRepaired = true;
+            }
+            const { subscriptions } = await shopify.admin.getActiveAppSubscriptions({
+              adminAccessToken,
+              domain: connection2.shop
+            });
+            if (subscriptions.length && subscriptions.every((subscription) => typeof subscription.metered === "boolean")) {
+              metered = subscriptions.some((subscription) => subscription.metered);
+            }
+          } catch (probeError) {
+            billingProbeFailed = true;
+            (_a = logger2 == null ? void 0 : logger2.warn) == null ? void 0 : _a.call(logger2, "shopify.health.billing.probe.failed", {
+              connectionId: connection2.id,
+              message: probeError == null ? void 0 : probeError.message,
+              shop: connection2.shop
+            });
+          }
+          if (sourceRepaired || metered !== null && metered !== (((_b = connection2.source) == null ? void 0 : _b.metered) ?? null)) {
+            writes.push({
+              collection: "connection",
+              data: {
+                $set: sourceRepaired ? { source: { ...source, ...metered !== null && { metered } } } : { "source.metered": metered }
+              },
+              operation: "update",
+              query: { id: connection2.id }
+            });
+          }
           return {
+            writes,
             enqueues: [{
               data: {
                 data: {
@@ -4073,13 +4187,19 @@ var shopify_default2 = {
               options: { jobId: "connection.update.register." + workflow.connection + "." + (0, import_node_crypto5.randomUUID)() },
               queue: "connection"
             }],
-            message: (scopesMissing == null ? void 0 : scopesMissing.length) ? "Health check: ping ok, webhooks reconciled \u2014 connection errored, granted scopes are missing: " + scopesMissing.join(", ") + "." : refreshTokenRotated ? "Health check passed \u2014 refresh token rotated, ping ok, webhooks reconciled." : "Health check passed \u2014 ping ok, webhooks reconciled.",
+            message: ((scopesMissing == null ? void 0 : scopesMissing.length) ? "Health check: ping ok, webhooks reconciled \u2014 connection errored, granted scopes are missing: " + scopesMissing.join(", ") + "." : refreshTokenRotated ? "Health check passed \u2014 refresh token rotated, ping ok, webhooks reconciled." : "Health check passed \u2014 ping ok, webhooks reconciled.") + (sourceRepaired ? " Billing source repaired from the live shop." : "") + (metered === false ? " No usage line on the store's approved plan \u2014 order billing needs the merchant to approve the updated plan." : ""),
             request: request2,
             response: {
+              billingProbeFailed,
+              metered,
               pingedAt: /* @__PURE__ */ new Date(),
               refreshTokenExpiresAt: refreshTokenExpiresAt || null,
               refreshTokenRotated,
               scopesMissing,
+              // The live settlement currency, for an operator — never
+              // written, see above.
+              ...shopCurrency && { shopCurrency },
+              sourceRepaired,
               webhookReconciliationQueued: true
             }
           };
@@ -4347,12 +4467,35 @@ var shopify_default2 = {
   //
   // Scope drift is NOT here: drawbridge-sync writes it onto the connection
   // document, and the document's own warnings render beside these.
-  tasks: (data2) => (data2 == null ? void 0 : data2.status) === "pending" ? [
-    {
-      message: "Open the Drawbridge app in your Shopify admin and choose a plan. The connection activates once Shopify confirms it.",
-      title: "Choose a plan in Shopify"
-    }
-  ] : [],
+  // Both cards carry `action : 'billing'`: the dashboard renders it as a real
+  // button that mints the corrective subscription (POST .../billing) and sends
+  // the owner to Shopify's confirmation screen — the fix lives in OUR
+  // dashboard, and the one Shopify-hosted step is the charge consent no app
+  // can perform for a merchant.
+  tasks: (data2) => {
+    var _a;
+    return [
+      ...(data2 == null ? void 0 : data2.status) === "pending" ? [
+        {
+          action: "billing",
+          message: "Approve the Drawbridge plan to activate this connection. You'll confirm the pricing on Shopify, then everything else happens here.",
+          title: "Approve your plan"
+        }
+      ] : [],
+      // The store's ACTIVE approval carries no usage component — stamped by
+      // the daily health check and the approval webhook (`source.metered`).
+      // Approved pricing is never retroactive, so the fix is a fresh approval.
+      // Gated on an EXPLICIT false — a connection the probe hasn't reached
+      // (or couldn't read) shows nothing rather than nagging on silence.
+      ...(data2 == null ? void 0 : data2.status) === "active" && ((_a = data2 == null ? void 0 : data2.source) == null ? void 0 : _a.metered) === false ? [
+        {
+          action: "billing",
+          message: "Order billing isn't set up for this store, so campaign-attributed orders aren't being charged. Approve the updated plan to fix it \u2014 one click here, one confirmation on Shopify.",
+          title: "Fix order billing"
+        }
+      ] : []
+    ];
+  },
   title: "Shopify"
 };
 
@@ -4526,6 +4669,9 @@ var webhook_default = {
   // Nothing to be exclusive with — there is no second webhook vendor, and a
   // merchant with two endpoints is a step-level choice rather than a second
   // connection.
+  // No vendor-facing event identities — declared empty so the contract stays
+  // explicit: a vendor that gains one adds it here, never as a side channel.
+  events: {},
   exclusive: false,
   feature: "organization:connection:webhook",
   fields: [
@@ -4817,16 +4963,16 @@ var connections = Object.freeze({
 (() => {
   var _a;
   const routes = {};
-  for (const [slug, manifest] of Object.entries(connections)) {
+  for (const [slug2, manifest] of Object.entries(connections)) {
     for (const [name, step] of leaves(manifest.steps)) {
       const type = "step." + name;
       const queue = (_a = step({})) == null ? void 0 : _a.queue;
       if (routes[type] && routes[type].queue !== queue) {
         throw new Error(
-          "Step " + type + " routes to " + routes[type].queue + " for " + routes[type].slug + " and " + queue + " for " + slug + " \u2014 one of them would be enqueued nowhere"
+          "Step " + type + " routes to " + routes[type].queue + " for " + routes[type].slug + " and " + queue + " for " + slug2 + " \u2014 one of them would be enqueued nowhere"
         );
       }
-      routes[type] = { queue, slug };
+      routes[type] = { queue, slug: slug2 };
     }
   }
 })();
@@ -4839,21 +4985,21 @@ var catalogConnections = (env = {}) => Object.fromEntries(
   Object.entries(availableConnections(env)).filter(([, manifest]) => !manifest.private)
 );
 var publicSettingsBySlug = Object.fromEntries(
-  Object.entries(connections).map(([slug, manifest]) => [
-    slug,
+  Object.entries(connections).map(([slug2, manifest]) => [
+    slug2,
     manifest.fields.filter((field2) => !field2.redact).map((field2) => field2.key)
   ])
 );
 var connectionSteps = (env = {}) => Object.entries(availableConnections(env)).flatMap(
-  ([slug, manifest]) => leaves(manifest.steps).map(([name, step]) => ({ ...step({}), slug, type: "step." + name }))
+  ([slug2, manifest]) => leaves(manifest.steps).map(([name, step]) => ({ ...step({}), slug: slug2, type: "step." + name }))
 );
 var hookSupport = (name) => ({
-  no: Object.keys(connections).filter((slug) => !implemented(connections[slug].hooks, name)),
-  yes: Object.keys(connections).filter((slug) => implemented(connections[slug].hooks, name))
+  no: Object.keys(connections).filter((slug2) => !implemented(connections[slug2].hooks, name)),
+  yes: Object.keys(connections).filter((slug2) => implemented(connections[slug2].hooks, name))
 });
-var connectFields = (slug) => {
+var connectFields = (slug2) => {
   var _a;
-  return (((_a = connections[slug]) == null ? void 0 : _a.fields) || []).map(({ copy, from, hook, input, key, label, message, options, placeholder, redact, required, search }) => ({
+  return (((_a = connections[slug2]) == null ? void 0 : _a.fields) || []).map(({ copy, from, hook, input, key, label, message, options, placeholder, redact, required, search }) => ({
     ...copy && { copy: true },
     ...hook && { hook },
     ...from && { from },
@@ -4873,18 +5019,18 @@ var connectFields = (slug) => {
     secret: Boolean(redact)
   }));
 };
-var runHook = async (slug, name, props = {}, options = {}) => {
-  const manifest = connections[slug];
-  if (!manifest) return { outcome: OUTCOMES.unsupported, reason: "no such connection: " + slug };
+var runHook = async (slug2, name, props = {}, options = {}) => {
+  const manifest = connections[slug2];
+  if (!manifest) return { outcome: OUTCOMES.unsupported, reason: "no such connection: " + slug2 };
   const hook = name.split(".").reduce(
     (node, key) => node && typeof node === "object" && Object.hasOwn(node, key) ? node[key] : void 0,
     manifest.hooks
   );
   if (hook === false || hook == null) {
-    return { outcome: OUTCOMES.unsupported, reason: slug + " does not implement " + name };
+    return { outcome: OUTCOMES.unsupported, reason: slug2 + " does not implement " + name };
   }
   if (typeof hook !== "function") {
-    return { outcome: OUTCOMES.unimplemented, reason: slug + " implements " + name + " outside this package" };
+    return { outcome: OUTCOMES.unimplemented, reason: slug2 + " implements " + name + " outside this package" };
   }
   try {
     const result = await hook({ ...props, manifest }, options);
@@ -4919,9 +5065,9 @@ var mergeSettings = ({ existing, incoming }) => {
   ;
   return merged;
 };
-var redactSettings = ({ slug, settings }) => {
+var redactSettings = ({ slug: slug2, settings }) => {
   if (!settings || typeof settings !== "object") return settings;
-  const allowed = publicSettingsBySlug[slug] || [];
+  const allowed = publicSettingsBySlug[slug2] || [];
   return Object.fromEntries(
     Object.entries(settings).filter(([key]) => allowed.includes(key))
   );