@syntrologie/runtime-sdk 2.8.0-canary.184 → 2.8.0-canary.186

package/dist/defaults/clickIds.d.ts

@@ -0,0 +1,14 @@
+/**
+ * D-4 — promote click IDs to person properties.
+ *
+ * Reads platform click-ID parameters (fbclid, ttclid, gclid, etc.)
+ * from the entry URL and writes them as $initial_<param> via
+ * setPersonPropertiesOnce. Survives the lifetime of the person record;
+ * pairs with Conversions API back-channels (Meta CAPI, TikTok Events
+ * API, etc.) when clients eventually run paid ads.
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md (D-4).
+ */
+import type { TelemetryClient } from '../telemetry/types';
+export declare const CLICK_ID_KEYS: readonly ["fbclid", "ttclid", "gclid", "gbraid", "wbraid", "msclkid", "twclid", "li_fat_id", "epik", "ScCid", "yclid", "_kx", "mc_eid", "mc_cid"];
+export declare function promoteClickIds(telemetry: TelemetryClient): void;

package/dist/defaults/identifyOnEmail.d.ts

@@ -0,0 +1,23 @@
+/**
+ * D-1 — auto-identify-or-alias on email entry.
+ *
+ * Listens for `change` events on email-typed inputs anywhere on the page.
+ * When a well-formed, non-denylisted email is detected:
+ *   - If the current distinct_id is anonymous (PostHog UUID): identify(email)
+ *   - If the current distinct_id is a different email: alias(email)
+ *   - If the same email was already seen this session: no-op
+ *
+ * Per-element opt-out via `data-syntro-no-identify` on the input or a
+ * parent form.
+ *
+ * Consent: when a ConsentGate is provided, the actual identify/alias
+ * call is gated on the gate's resolved status. Listener is always
+ * installed; the call only fires if the gate is (or resolves to) granted.
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md (D-1).
+ */
+import type { ConsentGate } from '../telemetry/consent';
+import type { TelemetryClient } from '../telemetry/types';
+export declare function isValidEmail(value: string): boolean;
+export declare function isEmailDenylisted(value: string): boolean;
+export declare function installEmailIdentifyListener(telemetry: TelemetryClient, consentGate?: ConsentGate): () => void;

package/dist/defaults/identifyOnUrlParam.d.ts

@@ -0,0 +1,29 @@
+/**
+ * D-2 — auto-identify-or-alias on URL param `?_syu=`.
+ *
+ * Reads the `_syu` (Syntro UID) param from the entry URL. If present:
+ *   - If the current distinct_id is anonymous: identify(value)
+ *   - If already identified as a different id: alias(value)
+ *   - If already this id: no-op
+ *
+ * v1 watches one hardcoded param (`_syu`). Clients embed it in their
+ * transactional emails. The config layer will eventually let clients
+ * register their own param keys; until then, `_syu` is the convention.
+ *
+ * Consent: param value is read at boot. The actual identify/alias call
+ * is deferred until the gate reaches `granted`. Importantly, we wait
+ * for the FIRST `granted` ever observed — not the first definitive
+ * status. Most CMPs (WPConsent, OneTrust, Cookiebot) push a
+ * `consent default { analytics_storage: 'denied' }` on page load,
+ * which would make our gate go denied → user clicks Accept → granted.
+ * If we used subscribeOnce, we'd unsubscribe on the initial denied
+ * and miss the user's actual decision. The fire-on-first-granted
+ * pattern preserves the magic-link identify even through the
+ * default-denied → granted flow.
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md (D-2).
+ */
+import type { ConsentGate } from '../telemetry/consent';
+import type { TelemetryClient } from '../telemetry/types';
+export declare const SYNTRO_UID_PARAM = "_syu";
+export declare function identifyFromUrlParam(telemetry: TelemetryClient, consentGate?: ConsentGate): void;

package/dist/defaults/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * SDK Default Instrumentation — public entry point.
+ *
+ * Wires up the five default behaviors specified in
+ * docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md:
+ *
+ *   D-1: auto-identify-or-alias on email entry
+ *   D-2: auto-identify-or-alias on URL param ?_syu=
+ *   D-3: capture $initial_* properties pre-identify
+ *   D-4: promote click IDs to person properties
+ *   D-5: extract JSON-LD raw and ship as event property
+ *
+ * All five are always on in v1. Per-element opt-outs via DOM
+ * attributes (data-syntro-no-track, data-syntro-no-identify,
+ * data-syntro-no-jsonld) are the only escape hatch.
+ */
+import type { ConsentGate } from '../telemetry/consent';
+import type { TelemetryClient } from '../telemetry/types';
+export { CLICK_ID_KEYS, promoteClickIds } from './clickIds';
+export { installEmailIdentifyListener, isEmailDenylisted, isValidEmail } from './identifyOnEmail';
+export { identifyFromUrlParam, SYNTRO_UID_PARAM } from './identifyOnUrlParam';
+export { captureInitialProperties } from './initialProperties';
+export { extractAndRegisterJsonLd, MAX_DESCRIPTION_LENGTH, MAX_IMAGE_ARRAY_LENGTH, PII_KEYS, stripBloat, stripPii, } from './jsonLd';
+interface GeoLike {
+    is_eu?: string;
+    country_code?: string;
+}
+interface InstallDefaultsOptions {
+    /**
+     * Promise resolving to geo info ({is_eu, country_code, ...}). Used by
+     * D-3 to decide whether to capture full URL (ROW) or origin+pathname
+     * only (EU/UK/CH). When omitted, D-3 captures the safe version.
+     */
+    geoPromise?: Promise<GeoLike>;
+}
+/**
+ * Install all SDK defaults. Returns a teardown function that removes
+ * any listeners that were attached.
+ *
+ * Safe to call when running in SSR / non-browser contexts; each
+ * default no-ops when the relevant browser APIs are unavailable.
+ *
+ * @param telemetry — the TelemetryClient (PostHog adapter, noop, etc.)
+ * @param consentGate — optional. When provided, D-1 (email entry) and
+ *        D-2 (URL param) consult the gate before calling identify/alias.
+ *        D-3, D-4, D-5 fire unconditionally — they're anonymous-only
+ *        operations against the current (likely anonymous) distinct_id.
+ * @param options — optional. `geoPromise` enables geo-aware URL capture
+ *        in D-3 (full URL for ROW, sanitized for EU/UK/CH).
+ */
+export declare function installDefaults(telemetry: TelemetryClient, consentGate?: ConsentGate, options?: InstallDefaultsOptions): () => void;

package/dist/defaults/initialProperties.d.ts

@@ -0,0 +1,26 @@
+/**
+ * D-3 — capture $initial_* properties pre-identify.
+ *
+ * On SDK init, write attribution properties to the (currently anonymous)
+ * person record via setPersonPropertiesOnce. PostHog's $set_once semantics
+ * mean these are immutable — first value wins. They survive across the
+ * lifetime of the person record and merge in retroactively when identify
+ * eventually fires.
+ *
+ * URL capture is geo-aware:
+ *   - ROW: capture full URL (`window.location.href`) including query string —
+ *     query params can carry useful attribution (custom ref codes, campaigns)
+ *     and ROW visitors can be tracked normally.
+ *   - EU/UK/CH: capture origin + pathname only. Query strings on entry URLs
+ *     can contain identifying info (`?_syu=alice@…`, `?email=…`, `?token=…`)
+ *     that we MUST NOT ship as a person property pre-consent.
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md (D-3).
+ */
+import type { TelemetryClient } from '../telemetry/types';
+interface GeoLike {
+    is_eu?: string;
+    country_code?: string;
+}
+export declare function captureInitialProperties(telemetry: TelemetryClient, geoPromise?: Promise<GeoLike>): void;
+export {};

package/dist/defaults/jsonLd.d.ts

@@ -0,0 +1,17 @@
+/**
+ * D-5 — extract JSON-LD raw and ship as event property.
+ *
+ * On every page navigation, scrape <script type="application/ld+json">
+ * blocks, strip PII keys + bloated fields, register the resulting
+ * array as `json_ld` so it flows onto subsequent events. Server-side
+ * picks what to make of it later — no schema vocabulary in SDK code.
+ *
+ * See docs/plans/current/2026-05-04-sdk-default-instrumentation-spec.md (D-5).
+ */
+import type { TelemetryClient } from '../telemetry/types';
+export declare const PII_KEYS: Set<string>;
+export declare const MAX_DESCRIPTION_LENGTH = 500;
+export declare const MAX_IMAGE_ARRAY_LENGTH = 3;
+export declare function stripPii(obj: unknown): unknown;
+export declare function stripBloat(obj: unknown): unknown;
+export declare function extractAndRegisterJsonLd(telemetry: TelemetryClient): void;