@drawbridge/drawbridge-agents 0.1.28 → 0.1.31

package/.claude-template/settings.json

@@ -21,6 +21,7 @@
       "../drawbridge-docs",
       "../drawbridge-emails",
       "../drawbridge-games",
+      "../drawbridge-growth",
       "../drawbridge-mongodb",
       "../drawbridge-redis",
       "../drawbridge-share",

package/conventions/cross-repo-contracts.md

@@ -68,13 +68,20 @@ skill) so it stops living only in tribal memory.
   after it produced five distinct defects, ending in a 60-second line-window overlap that billed
   one correctly-delivered event twice. Do not reintroduce meter events, and do not "fix" a billing
   discrepancy by reporting usage to Stripe — corrections are `billing.trueup` ledger rows.
-- **`items.actions` is the record of what the customer was SOLD** — `{ limit,
-  overageCentsPerAction }`, written by drawbridge-stripe (≥0.1.44) at create/upgrade/downgrade and
-  read by drawbridge-sync at cycle close. plans.js is the default for NEW sales only; editing it
-  does not reprice existing customers (that is `repriceActionsSnapshot`, explicit and dry-runnable).
-  Anything adding custom/enterprise pricing must gate the plan-change paths and the reprice script
-  or negotiated values get silently overwritten. The rate is a NUMBER in cents — the string
-  `'2.5'` shape exists only at the Stripe `unit_amount_decimal` boundary.
+- **`subscription.overrides` is the single home for sold/negotiated terms** —
+  `{ actions : { limit, overages }, conversion }`. `overrides.actions` is ALWAYS stamped at sale by
+  drawbridge-stripe (≥0.1.46) and re-stamped on plan change; `overrides.conversion` exists only when
+  an admin overrides the plan default, and api carries it onto the new document across plan changes.
+  Resolution is PER FIELD: `overrides.actions.X` → legacy `items.actions.X` (transitional) →
+  plans.js; conversion resolves ONLY through `conversionRate()` in utils (`overrides.conversion` →
+  legacy top-level `conversion` → plan → free; `??` throughout, 0 is a valid override). `overages`
+  is a NUMBER in cents per action — the string `'2.5'` shape exists only at the Stripe
+  `unit_amount_decimal` boundary. Deleting a key restores plan flow, which is why the admin PUT
+  unsets the legacy keys it supersedes. plans.js is the default for NEW sales only; repricing
+  existing customers is `repriceActionsSnapshot` (explicit, dry-runnable — and it overwrites
+  admin-negotiated actions values, so read the dry run). The legacy keys are copy-only until the
+  overrides cleanup release, and sync (reader) deploys before stripe (writer) on any shape change.
+  Detail: drawbridge-docs `reference/billing.md`.
 - **No Stripe product backs actions (≥0.1.45).** Invoice items carry
   currency/quantity/unit_amount_decimal/tax_behavior/description directly; the account keeps exactly
   one product — the plan product behind `STRIPE_PRICE_*`. Never reintroduce a product-presence guard
@@ -219,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.28",
+  "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.'
+	};
+
+});