@drawbridge/drawbridge-agents 0.1.12 → 0.1.16

package/claude/CLAUDE.md

@@ -12,6 +12,7 @@
 @../conventions/drawbridge-packages.md
 @../conventions/sentry-sdk.md
 @../conventions/app-web-forms.md
+@../conventions/app-web-gates.md
 @../conventions/docs-linkage.md
 @../conventions/superpowers-docs.md
 @../conventions/git-branching.md

package/conventions/app-web-gates.md

@@ -0,0 +1,22 @@
+# app-web gate helpers
+
+Applies to `drawbridge-app-web` only.
+
+UI gating goes through the shared helpers in `@/lib/helpers` — never inline the
+underlying object walks:
+
+- `hasCapability( organization, key, level = 'manage' )` — capability checks by
+  dot-path (`'campaigns.settings'`, `'brands'`). Never write
+  `organization?.capabilities?.x === 'manage'` inline; a missed optional chain
+  in that pattern has crashed pages before.
+- `hasConnection( organization, slug )` — "org has an ACTIVE connection for
+  this slug". Reads `connectionItems` from the org payload (see the
+  organization-payload contract in `cross-repo-contracts.md`); never fetch
+  `/organization/:id/connections` just to gate UI.
+- `hasRestriction( object, key )` — plan-limit restrictions on an org or
+  campaign.
+
+Compose extras (`getPlanFeature(...).granted`, totals checks) explicitly at the
+call site; the helpers stay single-purpose. Pass the org from the
+`[ 'organization', id ]` query cache (or an `enabled : false` `useQuery` on
+that key when the component must re-render as it refreshes).

package/conventions/cross-repo-contracts.md

@@ -26,6 +26,12 @@ skill) so it stops living only in tribal memory.
   `queue/index.js` together.
 - BullMQ jobs are keyed on the change-stream resume token as `jobId` for HA dedup across sync
   replicas. Reusing a static `jobId` with `removeOnComplete` makes re-enqueues no-op silently.
+- Scraped-asset file reuse keys on `organization + meta.origin + meta.element` **plus
+  `meta.render` for pipeline-rendered marks** (sync `resolveAsset` writes/queries it; the field
+  and its index live in drawbridge-api `schema/file.js`). `origin` identifies the source asset,
+  `render` content-hashes the rendered output — drop `render` from either side and a rendering
+  fix never ships: reuse serves the first-ever render forever (the onemethod
+  black-on-black-logo-twice bug).
 
 ## Billing / metering
 
@@ -46,7 +52,26 @@ skill) so it stops living only in tribal memory.
   worker retries it into the update path. The merge path must delete duplicate contacts BEFORE
   `$set`-ing the survivor (the expanded `leads` array collides with rows about to be deleted).
   Drop the index → duplicate contacts, doubled segment members, double-billed `contact.create` +
-  `segment.join`; reorder the merge → every merge aborts E11000 and duplicates never heal.
+  `segment.join`; reorder the merge → every merge aborts E11000 and duplicates never heal. The
+  merge path also reverses each merged-away contact's **current-period** `action` rows (matched by
+  `meta.contact`, in the billing transaction) so the survivor isn't billed once per duplicate.
+- The `action` ledger's **`{ organization : 1, createdAt : 1 }` index** (drawbridge-api
+  `schema/action.js`) is a shared dependency: sync's `computeCycleActions` (billing, by `createdAt`
+  window) AND api's date-ranged reporting (`route/organization-usage.js`) both match on it. Drop it
+  → COLLSCAN on every invoice + usage query.
+- The `action` ledger is **permanent — no TTL** (drawbridge-api `schema/action.js`): the
+  proof-of-billing record AND the source for date-ranged usage reporting, both read as raw rows by
+  `createdAt`. Re-adding a TTL shorter than any billing interval silently under-bills long cycles
+  and blanks reporting past the window — any retention change must clear billing + reporting.
+
+## Reporting (api ↔ app-web)
+
+- Every reporting request (usage/revenue/redemptions/analytics, org + admin) carries the viewer's
+  IANA `timezone` (app-web sends `Intl.DateTimeFormat().resolvedOptions().timeZone`); drawbridge-api
+  buckets the date range in it via `lib/report-window.js` (half-open UTC window, defaults to UTC when
+  absent). app-web omitting it → ranges bucket by UTC not the user's calendar days (boundary events
+  land on the wrong day). The param rides each endpoint's existing query shape (top-level vs
+  `filters`) — do NOT normalise the shapes.
 
 ## `@drawbridge/*` package coordination
 
@@ -75,3 +100,19 @@ 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.
+- `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
+  page. A scope added to the toml but not the constant silently escapes the check; one added to
+  the constant but not the toml flags every store forever.
+
+## Organization payload (api ↔ app-web)
+
+- `connectionItems` on the org payload comes only from drawbridge-api
+  `extend.organization({ connections : true })` (org GET + org menu opt in via
+  `hasOrganizationAccess`); app-web's `hasConnection` helper (`lib/helpers.js`) and api's
+  `lib/tasks.js connectionErrors` read it. Two invariants: the lookup's `$project`
+  (id/slug/status/title/shop/errors) is a **security boundary** — the org response spreads to the
+  browser, so adding a credential field ships connection tokens to every dashboard user; and api
+  deploys before app-web — the gate treats a missing field as "no connection" and silently hides
+  connection-gated UI (e.g. the campaign Shop product columns row).

package/package.json

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