@ssheleg/sheleg-dev 0.5.2 → 0.7.0

package/plugins/sheleg-dev/skills/ad-tracking/fixtures/reference-emitter.mjs

@@ -0,0 +1,129 @@
+// A purchase emitter that satisfies the deduplication contract this skill states, and the
+// same emitter with one rule removed at a time.
+//
+// Two call sites, and which one may report a purchase is the whole invariant:
+//
+//   onChargeCleared(purchase)  <- the webhook handler, the only place that knows the money
+//                                 moved. Sends the Conversions API event.
+//   onThankYouPage(purchase)   <- the browser. Fires the pixel with the id the server will
+//                                 reuse, and reports nothing on its own authority.
+//
+// `without: ['shared-event-id']` and friends delete the lines a generated integration
+// routinely omits; `fixtures/README.md` shows the code each flag removes. Nothing here
+// reaches the network — the sink collects what WOULD have been sent, which is what the
+// assertions read. No access token appears in this directory at all.
+
+export const RULES = Object.freeze([
+  'shared-event-id',
+  'exact-event-name',
+  'webhook-sourced',
+  'keep-browser-event',
+  'hashed-identifiers',
+]);
+
+/** Meta compares `event_name` as well as the id, and it is the half that gets missed. */
+export const EVENT_NAME = 'Purchase';
+
+export function createSink() {
+  return { pixel: [], capi: [] };
+}
+
+function customData(purchase) {
+  return {
+    value: purchase.value,
+    currency: purchase.currency,
+    content_ids: purchase.contentIds,
+    content_type: 'product',
+    num_items: purchase.numItems,
+  };
+}
+
+export function createEmitter(sink, options = {}) {
+  const without = new Set(options.without || []);
+  for (const rule of without) {
+    if (!RULES.includes(rule)) throw new Error(`unknown rule: ${rule}`);
+  }
+  const has = (rule) => !without.has(rule);
+  let generated = 0;
+
+  /** One id, generated once at session creation, carried by both sides. */
+  function eventIdFor(purchase) {
+    if (has('shared-event-id')) return purchase.conversionEventId;
+    generated += 1;
+    return `evtid_generated_at_emission_${generated}`;
+  }
+
+  function eventNameFor(side) {
+    if (has('exact-event-name')) return EVENT_NAME;
+    // The trap: an id that matches and a name that does not deduplicates nothing.
+    return side === 'server' ? EVENT_NAME.toLowerCase() : EVENT_NAME;
+  }
+
+  function userData(purchase) {
+    const identifiers = has('hashed-identifiers')
+      ? { em: [purchase.emailSha256], external_id: [purchase.externalId] }
+      : { em: [purchase.email], external_id: [purchase.externalId] };
+    return {
+      ...identifiers,
+      client_ip_address: purchase.clientIpAddress,
+      client_user_agent: purchase.clientUserAgent,
+      fbp: purchase.fbp,
+      fbc: purchase.fbc,
+    };
+  }
+
+  function capiBody(purchase) {
+    return {
+      data: [{
+        event_name: eventNameFor('server'),
+        event_time: purchase.eventTime,
+        event_id: eventIdFor(purchase),
+        event_source_url: purchase.eventSourceUrl,
+        action_source: 'website',
+        user_data: userData(purchase),
+        custom_data: customData(purchase),
+      }],
+    };
+  }
+
+  return {
+    /** The webhook handler. `cleared` is the provider's word, not the browser's. */
+    onChargeCleared(purchase) {
+      if (purchase.cleared !== true) {
+        // Reached only by a caller that guessed. The gate below is the one that matters.
+        return { sent: false, why: 'the charge has not cleared' };
+      }
+      sink.capi.push(capiBody(purchase));
+      return { sent: true };
+    },
+
+    /**
+     * The thank-you page. It fires the pixel and NOTHING ELSE: a browser cannot know
+     * whether the charge cleared, and for an async method it usually has not.
+     */
+    onThankYouPage(purchase) {
+      if (!has('webhook-sourced')) {
+        // The defect: reporting the purchase from the one place with no idea whether the
+        // money moved. `purchase-capi-from-thank-you-page.json` is what this sends.
+        sink.capi.push(capiBody(purchase));
+      }
+      if (has('webhook-sourced') && purchase.cleared !== true) {
+        // Not even the pixel: a Purchase fired here exists for every session that reached
+        // the page, including the ones that never paid.
+        return { fired: false, why: 'the charge has not cleared' };
+      }
+      if (!has('keep-browser-event')) {
+        // The other direction: dropping the browser event loses the click ids, the consent
+        // state and the session that only the browser carries.
+        return { fired: false, why: 'browser event removed' };
+      }
+      sink.pixel.push([
+        'track',
+        eventNameFor('browser'),
+        customData(purchase),
+        { eventID: eventIdFor(purchase) },
+      ]);
+      return { fired: true };
+    },
+  };
+}

package/plugins/sheleg-dev/skills/ad-tracking/references/event-tracking.md

@@ -201,3 +201,45 @@ function trackEvent(name, params) {
   gtag('event', name, params);
 }
 ```
+
+---
+
+## User identification
+
+### Cross-Platform Identification Strategy
+
+| Platform | Method | When | What it enables |
+|---|---|---|---|
+| GA4 | `user_id` via `gtag('config', TAG_ID, { user_id })` | After login/onboarding | Cross-device tracking, audience building |
+| GA4 | Enhanced Conversions via `gtag('set', 'user_data', { email })` | After login/onboarding | Better conversion attribution |
+| Meta Pixel | Advanced Matching via `fbq('init', PIXEL_ID, { em, fn })` | After login/onboarding | Better conversion attribution, larger custom audiences |
+| Mixpanel | `alias()` + `identify()` | After login/onboarding | Merge anonymous → identified user profiles |
+
+**All identification calls should be placed in a single identification component** that runs in the dashboard/authenticated layout. This ensures:
+- User data is sent once per session
+- All platforms receive identification data at the same time
+- Pre-login anonymous events merge into the identified profile
+
+### Alias vs Identify (Mixpanel)
+
+- `alias(userId, anonymousId)` — creates a permanent link between the anonymous and real user ID. Must be called **exactly once** per user, **before** `identify()`. Use a localStorage flag to prevent duplicate calls.
+- `identify(userId)` — sets the user ID for all subsequent events.
+
+### Timing
+
+Fire identification in a `useEffect` in the authenticated layout:
+
+```typescript
+useEffect(() => {
+  // 1. Mixpanel alias + identify
+  // 2. GA4 user_id + Enhanced Conversions
+  // 3. Meta Advanced Matching
+}, [userId, email, name]);
+```
+
+---
+
+Moved out of `SKILL.md` on 2026-08-16: the body was 5273 tokens against a
+< 5000 budget, and identity is the other half of the question this file already
+owns — an event name says what happened, identity says who it happened to.
+

package/plugins/sheleg-dev/skills/ad-tracking/references/meta-linkedin.md

@@ -9,9 +9,13 @@ setup snippet and the traps.
 ## Contents
 
 - [Parameter object properties](#parameter-object-properties) — what Meta accepts per event
+- [Standard events](#standard-events) — the seventeen, and the four that carry a funnel
 - [Firing events](#firing-events) — the wrapper and its consent gate
-- [Advanced matching](#advanced-matching) — hashed identifiers, and what must never be sent
-- [Everything below](#) — LinkedIn conversion detail, deduplication with CAPI
+- [Advanced matching](#advanced-matching) — hashed identifiers
+- [What must never be sent](#what-must-never-be-sent) — the categories that are a terms breach, not a tuning choice
+- [Deduplication with the Conversions API](#deduplication-with-the-conversions-api) — the contract that stops one purchase counting twice
+- [LinkedIn conversion tracking](#linkedin-conversion-tracking) — Insight Tag, Campaign Manager rules, `lintrk`
+- [Meta Events Manager verification](#meta-events-manager-verification) — reading it back
 
 ### Parameter Object Properties
 
@@ -28,6 +32,22 @@ setup snippet and the traps.
 | `predicted_ltv` | float | Predicted lifetime value (for Subscribe) |
 | `status` | boolean | Registration status (for CompleteRegistration) |
 
+### Standard Events
+
+Meta defines 17 standard events. The most important for SaaS conversion funnels:
+
+| Event | When | Parameters | Notes |
+|---|---|---|---|
+| `PageView` | Every page load | (automatic from base code) | Fires from the init script |
+| `CompleteRegistration` | User signs up | `content_name` (method), `status: true` | Separate from GA4 `sign_up` |
+| `InitiateCheckout` | Checkout started | `value`, `currency`, `content_name`, `content_category`, `num_items` | |
+| `Purchase` | Purchase completed | `value` (required), `currency` (required), `content_name`, `content_category`, `content_type`, `contents[]` | `value` + `currency` are **mandatory** for optimisation |
+| `Subscribe` | Recurring subscription | `value`, `currency`, `predicted_ltv` | Distinct from one-time Purchase |
+| `Lead` | Lead form submitted | (optional params) | |
+| `ViewContent` | Key content viewed | `content_name`, `content_category` | |
+| `AddToCart` | Item added to cart | `content_name`, `value`, `currency` | |
+| `Search` | Search performed | `search_string` | |
+
 ### Firing Events
 
 ```javascript
@@ -75,6 +95,143 @@ export function setFbAdvancedMatching(data: { em?: string; fn?: string }) {
 }
 ```
 
+### What must never be sent
+
+Advanced Matching is the one place a tracking integration can breach Meta's terms
+by accident, because the wrapper accepts whatever you hand it and hashes it
+without judgement. SHA-256 does **not** make a value safe to send: hashing is a
+matching mechanism, not a permission. That the wrapper receives a hash at all is checkable:
+`identifiers-reach-the-server-hashed` in `fixtures/assert-dedup-contract.mjs` requires every
+`user_data.em` entry to be 64 hex characters and refuses anything with an `@` in it. What may
+be hashed in the first place is the table below, and no assertion decides it.
+
+Meta's Business Tools Terms prohibit sharing data that "includes or is based on"
+any of these, and the prohibition covers the Pixel, the Conversions API, the
+Facebook SDK for App Events, Offline Conversions and the App Events API alike:
+
+| Never send | Why it is not a judgement call |
+|---|---|
+| Health information | Named in the terms. Meta also runs a signals-filtering mechanism that drops data it categorises as potentially health-related before it reaches ads ranking — so the data is both a breach and useless |
+| Financial information | Named in the terms |
+| Consumer report information | Named in the terms |
+| Social security numbers, credit card numbers | Named as identifiers Meta does not permit |
+| Data from or about children under 13 | Named in the terms |
+| Anything sensitive under applicable law or industry guidance | The terms defer to local definitions, so the list above is a floor and not a ceiling |
+
+**The event NAME is covered too**, and this is the half integrations miss: "the
+names you choose and criteria you establish for your events, conversions, and any
+custom audiences you create must not reflect, imply or be based on any category of
+sensitive information." A `trackCustom('DiabetesPlanPurchase')` is a breach with
+an empty parameter object.
+
+**The practical rule:** the eleven Advanced Matching keys — `em`, `fn`, `ln`,
+`ph`, `external_id`, `ge`, `db`, `ct`, `st`, `zp`, `country` — are the whole
+allowed surface. Anything you were about to add beside them is the thing to stop
+and check.
+
+Source: Meta Business Tools Terms and the Sensitive Health Information help
+centre, read 2026-08-16. Re-read before quoting: the categories move.
+
+### Deduplication with the Conversions API
+
+**Send both, and let Meta discard one.** Browser and server events are not an
+either/or — the pixel is blocked often enough that server-side is the reliable
+source, and the browser event carries signals the server cannot see. The whole
+job is making sure the pair collapses into one conversion instead of two.
+
+**Two fields must match, not one.** Meta compares:
+
+| Pixel | Conversions API |
+|---|---|
+| `eventID` | `event_id` |
+| `event` (the event name) | `event_name` |
+
+Both. An integration that generates a shared `event_id` and lets the two sides
+disagree on the name — `Purchase` in the browser, `purchase` on the server — has
+two events that will never deduplicate, and the revenue is counted twice. This is
+the single most common way this goes wrong, because the `event_id` half is
+obvious and the `event_name` half is not.
+
+**The window is 48 hours**, and it runs from when Meta receives the *first* event
+carrying a given `event_id` — not from when the purchase happened. A server event
+retried out of a dead-letter queue two days later is a second conversion.
+
+```javascript
+// One id, generated once, used by both sides.
+const eventId = crypto.randomUUID();
+
+// Browser
+fbq('track', 'Purchase', { value: 30.00, currency: 'USD' }, { eventID: eventId });
+
+// Server — the SAME event_name string, not a variant
+await sendCapi({
+  event_name: 'Purchase',     // must equal the pixel's 'Purchase' exactly
+  event_id: eventId,
+  event_time: Math.floor(Date.now() / 1000),
+  action_source: 'website',
+  user_data: { /* hashed */ },
+  custom_data: { value: 30.00, currency: 'USD' },
+});
+```
+
+**The alternative method, and its trap.** Where you cannot thread an id through,
+Meta will also deduplicate on `event_name` plus `fbp` and/or `external_id`, held
+consistent across both sources. It is weaker in a specific direction: *"server
+events will not be discarded if a browser event has not been received in the past
+48 hours, even if an identical browser event arrives after the server event."*
+So the browser event must arrive **first**. For a purchase confirmed by a webhook
+— which is the pattern this skill teaches, because the webhook is the payment —
+the server event usually arrives first, and this method then does nothing. Use
+`event_id`.
+
+Neither method deduplicates within a single source: two pixel fires of the same
+purchase are two conversions no matter what.
+
+**Proved, not asserted.** `fixtures/purchase-pixel-browser.json` and
+`fixtures/purchase-capi-server.json` are the two payloads one purchase produces, and
+`fixtures/assert-dedup-contract.mjs` compares them: `pixel-and-capi-carry-one-event-name`
+fails an emitter that sends `Purchase` from the browser and a lowercased variant from the
+server, which is the half of this contract that gets missed. The shape itself is a ratchet —
+`the-shipped-capi-fixture-is-what-a-correct-emitter-sends` requires the emitted body to equal
+the fixture byte for byte, so **the fixtures are the reference output rather than an
+illustration**.
+
+Source: [Deduplicate pixel and Conversions API
+events](https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events),
+read 2026-08-16.
+
+### LinkedIn conversion tracking
+
+**Env var:** `NEXT_PUBLIC_LINKEDIN_PARTNER_ID` (numeric string).
+
+The Insight Tag is consent-gated on the same wrapper as the Meta Pixel — it loads
+`insight.min.js` and ships a `noscript` pixel fallback.
+
+```javascript
+_linkedin_partner_id = "PARTNER_ID";
+window._linkedin_data_partner_ids = window._linkedin_data_partner_ids || [];
+window._linkedin_data_partner_ids.push(_linkedin_partner_id);
+```
+
+**Conversions are configured in Campaign Manager, not in code.** The Insight Tag
+tracks page views by itself, and URL rules match those page loads to conversions:
+
+1. Campaign Manager → Analyze → Conversion tracking → Create conversion
+2. Define the URL rules (`/thank-you`, `/onboarding`)
+3. The tag matches page loads against them
+
+For an event-based conversion rather than a URL one:
+`window.lintrk('track', { conversion_id: 123456 })`.
+
+**LinkedIn has no equivalent of the `event_id` contract above.** There is no
+browser/server pair to deduplicate here, which is why a URL rule that matches a
+page a user can refresh counts every refresh — put the rule on a page reached once,
+or use `lintrk` from the code path that actually completed the action.
+
+**Docs:**
+- [LinkedIn Insight Tag setup](https://www.linkedin.com/help/lms/answer/a418880)
+- [LinkedIn conversion tracking](https://www.linkedin.com/help/lms/answer/a423304)
+
 ### Meta Events Manager Verification
 
 1. Install the **Meta Pixel Helper** Chrome extension

package/plugins/sheleg-dev/skills/crypto-payments/SKILL.md

@@ -45,6 +45,7 @@ and anything else that issues an invoice and calls you back.
 - [Reconciliation fields](#reconciliation-fields)
 - [Crediting: the amount waterfall](#crediting-the-amount-waterfall)
 - [Refunds and AML holds](#refunds-and-aml-holds)
+- [The test/live credential boundary](#the-testlive-credential-boundary)
 - [Local development](#local-development)
 - [Test matrix](#test-matrix)
 - [Security checklist](#security-checklist)
@@ -309,6 +310,68 @@ Crypto has no chargeback, which people mistake for "no reversals".
 - **Never auto-refund from the webhook.** Route holds and refunds to a queue a
   human can see.
 
+**And make it a precondition, not a paragraph.** The three lines above were advice for
+four releases: an agent that never read them, and a shell nobody read, were unaffected by
+all three. This pack now ships a `PreToolUse` gate —
+`plugins/sheleg-dev/hooks/money-gate.js` — that refuses a refund, a payout, closing a
+dispute, an export of `HELEKET_API_KEY` in a run declaring `test`, a live `sk_live_…` key
+and `SKIP_BILLING=true` in production, until the authorised person has signed that
+category off for the session. The pack's `README.md` carries the categories and how one is
+authorised. In your application the same rule is a queue and a human; in the agent's
+shell it is the hook.
+
+---
+
+## The test/live credential boundary
+
+**Establish what the provider actually offers before designing around it.** Card
+processors hand you two parallel worlds — Stripe gives a whole second account and stamps
+the environment into the key itself (`sk_test_` / `sk_live_`). Most crypto gateways do
+not. Answer these three, from the provider's documentation, and write the answers down:
+
+1. **Is there a separate test credential?** Not "a test mode" — a *different secret*.
+2. **Can the environment be read from the key?** A prefix, a scope, anything.
+3. **Does the key also sign webhooks?** If yes, it cannot be scoped down: everything that
+   verifies a callback can also create a charge.
+
+The answers decide the design, and the worst combination is common: one key, no marker,
+"test mode" as a **toggle on the merchant account**. Then the same secret creates play
+invoices before somebody moves a dashboard switch and real ones after — with no deploy and
+no signal to any machine holding it.
+
+**Build the strongest control the provider allows, in this order:**
+
+1. **A separate sandbox account**, so the credential on a dev machine *cannot* reach
+   production. This is the only control that still works after everyone has forgotten why
+   it is there — which is the whole argument for preferring it to a warning in a README.
+2. **A declared environment plus a boot assertion**, when there is no second credential.
+   Keep the declaration in a variable **separate from the secret** (`<PROVIDER>_ENV=test|
+   production`): one variable that both carries the key and names its environment cannot
+   be checked against itself, two can. Pin the production identity with something
+   non-secret — the merchant id, or a truncated hash of the live key — and refuse
+   **both** mismatches at **startup**:
+
+   - a live credential declared test — the obvious loss;
+   - a test credential declared live — the quiet one, where invoices settle to a merchant
+     nobody reconciles and nothing errors until revenue is missing.
+
+   Assert at module load, not in the payment handler: a run that merely *holds* the key
+   must fail too, and it is agent and CI runs that hold keys without ever charging
+   anything. And when the check cannot tell — nothing pinned — refuse on the test side.
+   "Could not prove it was safe" must never read as "it was safe".
+3. **Write down what is left.** Where the provider offers no test credential, a developer
+   holds a production one and the assertion narrows that window without closing it. An
+   unavoidable exposure that is named is a different object from one that is silent: the
+   first gets rotated, monitored and revisited, the second gets rediscovered by an
+   incident.
+
+The same rule applies to the mock path below: `SKIP_BILLING=true` in production is not a
+shortcut, it is a free-money path, and the assertion is what refuses it.
+
+Worked end to end for one gateway with no test credential at all —
+[`references/heleket-provider.md`](references/heleket-provider.md), *The test/live
+boundary* and *Residual exposure*.
+
 ---
 
 ## Local development
@@ -363,6 +426,9 @@ Cover these, and plant a defect against each before believing the green:
 - [ ] CSRF exempted for exactly one path, by exact match
 - [ ] Entitlement never granted from a client-side redirect
 - [ ] API key and merchant id from environment, never in the repository
+- [ ] A sandbox account is used where the provider offers one, or the reason it cannot be is written down
+- [ ] The declared environment is a variable separate from the secret, and a boot assertion refuses **both** mismatches
+- [ ] The assertion runs at module load, so a run that only holds the key fails too
 - [ ] Callback URL is HTTPS in every environment that is not a local tunnel
 - [ ] `SKIP_BILLING` asserted impossible in production
 - [ ] Reconciliation fields written at settlement time
@@ -382,3 +448,5 @@ Cover these, and plant a defect against each before believing the green:
 | "Paid" users with no product | credited from the browser redirect |
 | Half the payments land as `wrong_amount` | no conversion buffer |
 | Cannot answer "how much did we net" | commission and `merchantAmount` never stored |
+| A dev machine, a CI job or an agent run is holding the production key | no separate credential, and no assertion binding the key to a declared environment |
+| Real invoices in a merchant dashboard nobody watches | a staging credential declared live — the mismatch nothing refused |