@drawbridge/drawbridge-agents 0.1.30 → 0.1.31

package/conventions/cross-repo-contracts.md

@@ -226,6 +226,20 @@ skill) so it stops living only in tribal memory.
 - The `write_resource_feedbacks` and `read_publications` scopes live in drawbridge-shopify-app's
   `shopify.app.*.toml` but power other repos: sync's product ResourceFeedback sends and the
   embedded app's publishing section. Removing either → silent Shopify userErrors, no crash.
+- **No Shopify webhook reaches the embedded app.** Every `[[webhooks.subscriptions]]` in
+  drawbridge-shopify-app's `shopify.app.*.toml` — `app/uninstalled` included — is delivered to
+  drawbridge-webhooks (`route/shopify.js`, topic-agnostic → `buffer` doc), which drawbridge-sync
+  consumes (`lib/buffer.js` `shopify.app/uninstalled` → delete connections, hard-delete the `shop`
+  record). So `app/routes/webhooks.app.uninstalled.tsx` is unreachable and **nothing in the
+  embedded app may hold per-shop state that needs invalidating on uninstall** — no memo, no cache,
+  no "already done" set. Violated once: `ensureChannel` cached "this shop is bound to our channel
+  spec" in a process-local Set cleared only by that dead route, so uninstall → reinstall skipped
+  `channelCreate` and the merchant silently lost the Drawbridge sales channel (2026-08-07 QA).
+- Shopify Admin GraphQL failures come in **two shapes**, and sales-channel code must handle both:
+  domain failures land in `userErrors` (HTTP 200), while a revoked/expired offline token,
+  throttling, or a field missing on the API version land in a **top-level `errors`** — a bare
+  string for a 401, an array of objects otherwise — with a null `data`. Reading only `userErrors`
+  turns an auth failure into a silent success.
 - `SHOPIFY_REQUIRED_SCOPES` (`@drawbridge/shopify` `lib/constants.js`) must stay in lockstep with
   `[access_scopes]` in drawbridge-shopify-app's `shopify.app.*.toml` (both files). drawbridge-api
   diffs each store's granted scopes against it to flag "update permissions" on the connections

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {

package/scripts/channels.js

@@ -0,0 +1,88 @@
+// What communication channels are actually flowing, HubSpot's count against ours.
+//
+// Exists because "the integration is connected" and "the data is arriving" are
+// different claims, and the second is the only one that matters here. HubSpot's
+// communication object holds SMS, WhatsApp and LinkedIn messages, told apart by
+// channel — so whatever writes LinkedIn messages into that object, this pipeline
+// reads. The question is never whether we can read them; it is whether anything is
+// writing them.
+//
+// Same shape as the `missing` figure on the contact ingest, which is what caught 50
+// contacts that had been silently absent for the life of the project.
+
+const { growth } = require( '../lib/mongodb' );
+const { enabled, request } = require( '../lib/hubspot' );
+const { run } = require( '../lib/cycle' );
+
+// The channels HubSpot files under the communication object. PHYSICAL_MAIL is
+// hidden on this portal but counted anyway, because a hidden property still holds
+// records.
+const CHANNELS = [
+	'LINKEDIN_MESSAGE',
+	'SMS',
+	'WHATS_APP',
+	'PHYSICAL_MAIL',
+	'CUSTOM_CHANNEL_CONVERSATION'
+];
+
+run( 'channels', async () => {
+
+	if( ! enabled() ) return { skipped : 'HUBSPOT_ACCESS_TOKEN not set' };
+
+	const { db, database } = await growth();
+
+	const report = {};
+
+	for( const channel of CHANNELS ){
+
+		const body = await request({
+			body : {
+				filterGroups : [
+					{
+						filters : [
+							{
+								operator : 'EQ',
+								propertyName : 'hs_communication_channel_type',
+								value : channel
+							}
+						]
+					}
+				],
+				limit : 1
+			},
+			method : 'POST',
+			path : '/crm/v3/objects/communications/search'
+		});
+
+		const inHubspot = Number( body?.total || 0 );
+
+		// Ours is counted on the touch, which is one row per contact on the message,
+		// so it can legitimately exceed HubSpot's count of messages.
+		const held = await database.collection( 'touch' ).countDocuments({
+			channel,
+			type : 'communication'
+		});
+
+		report[ channel ] = {
+			held,
+			inHubspot,
+			// The number that answers "is anything writing this channel".
+			missing : inHubspot === 0 ? 0 : Math.max( 0, inHubspot - held )
+		};
+
+	}
+
+	const flowing = Object.entries( report )
+		.filter( ( [ , value ] ) => value.inHubspot > 0 )
+		.map( ( [ key ] ) => key );
+
+	return {
+		byChannel : report,
+		// Empty means nothing outside email, calls, meetings, notes and tasks is
+		// reaching HubSpot at all - which is a setup answer, not a pipeline answer.
+		flowing : flowing.length ? flowing : 'nothing beyond email/calls/meetings/notes/tasks',
+		note : 'LINKEDIN_MESSAGE at 0 means no tool is writing LinkedIn messages into'
+			+ ' HubSpot. Whatever writes them, this pipeline already reads them.'
+	};
+
+});