@getrheo/attribution 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+import { FlowManifest } from '@getrheo/contracts/manifest';
+import { DecisionExpr, DecisionNode } from '@getrheo/contracts/decisions';
+import { z } from 'zod';
+
+/**
+ * Universal SDK attribute keys for mobile attribution / deep-link context.
+ * Provider adapters (AppsFlyer, Adjust, …) map native payloads → these names.
+ *
+ * Host-supplied `sdkAttributes` should avoid these prefixes to prevent clashes:
+ * `attribution.`, `acquisition.`, `link.`
+ */
+/** Metadata about which MMP / SDK produced the current snapshot (string id, e.g. `appsflyer`). */
+declare const ATTR_KEY_PROVIDER: "attribution.provider";
+/** Whether the install/open was classified as organic (`boolean` in decision eval). */
+declare const ATTR_KEY_IS_ORGANIC: "attribution.isOrganic";
+/** Optional coarse confidence hint from the provider (`high` | `medium` | `low`). */
+declare const ATTR_KEY_CONFIDENCE: "attribution.confidence";
+/** Provider-specific match type string when available (probabilistic, etc.). */
+declare const ATTR_KEY_MATCH_TYPE: "attribution.matchType";
+/** Media / network / channel — paid ads, social, search, etc. */
+declare const ATTR_KEY_ACQ_SOURCE: "acquisition.source";
+declare const ATTR_KEY_ACQ_CAMPAIGN: "acquisition.campaign";
+declare const ATTR_KEY_ACQ_CAMPAIGN_ID: "acquisition.campaignId";
+declare const ATTR_KEY_ACQ_ADSET: "acquisition.adset";
+declare const ATTR_KEY_ACQ_ADSET_ID: "acquisition.adsetId";
+declare const ATTR_KEY_ACQ_CREATIVE: "acquisition.creative";
+declare const ATTR_KEY_ACQ_CREATIVE_ID: "acquisition.creativeId";
+/** Optional coarse channel bucket (e.g. social, search). */
+declare const ATTR_KEY_ACQ_CHANNEL: "acquisition.channel";
+/**
+ * Primary entry identifier from a universal / deep link — same decision surface as campaigns.
+ * Semantic: “what route or offer this open represents”.
+ */
+declare const ATTR_KEY_LINK_ENTRY: "link.entry";
+/**
+ * Flattened dynamic params from links / deferred payloads.
+ * Pattern: `link.ext.<paramKey>` where paramKey is provider-normalized (alphanumeric + underscore).
+ */
+declare const LINK_EXT_PREFIX: "link.ext.";
+/** Well-known link.param keys (optional convenience aliases providers may map). */
+declare const ATTR_KEY_LINK_REFERRAL: "link.ext.referral_code";
+declare const ATTR_KEY_LINK_PROMO: "link.ext.promo_code";
+declare const ATTR_KEY_LINK_CONTENT_ID: "link.ext.content_id";
+
+/**
+ * Provider-agnostic attribution context produced by MMP adapters before flattening to sdkAttributes.
+ */
+type AttributionConfidenceLevel = 'high' | 'medium' | 'low';
+/** Stable identifier for an attribution SDK integration (`appsflyer`, `adjust`, …). */
+type AttributionProviderId = string;
+interface AttributionFacet {
+    /** Organic vs paid/non-organic classification when available. */
+    isOrganic?: boolean;
+    matchType?: string;
+    confidence?: AttributionConfidenceLevel;
+    /** Epoch ms when install occurred (from provider when present). */
+    installTimestampMs?: number;
+    /** Epoch ms for attributed click when present. */
+    clickTimestampMs?: number;
+}
+interface AcquisitionFacet {
+    source?: string;
+    campaign?: string;
+    campaignId?: string;
+    adset?: string;
+    adsetId?: string;
+    creative?: string;
+    creativeId?: string;
+    channel?: string;
+}
+/**
+ * Deep links / universal links use the same branching surface as acquisition — primary route plus extensible params.
+ */
+interface LinkFacet {
+    /** Primary entry / route / deep-link value (harmonized across providers). */
+    entry?: string;
+    /** Arbitrary key/value pairs (merged into `link.ext.*` flat keys). */
+    params?: Record<string, string>;
+}
+/**
+ * Single normalized snapshot emitted by an {@link AttributionProviderId}.
+ * Multiple facets may be filled from install conversion, deep link, or both.
+ */
+interface NormalizedAttributionSnapshot {
+    providerId: AttributionProviderId;
+    /** When this snapshot was captured on-device (epoch ms). */
+    capturedAtMs: number;
+    attribution: AttributionFacet;
+    acquisition: AcquisitionFacet;
+    link: LinkFacet;
+}
+
+/**
+ * Maps a normalized snapshot into flat `sdkAttributes` entries for decision nodes.
+ * Omits undefined leaves; booleans stay booleans for boolean predicates.
+ */
+declare const flattenAttributionSnapshotToSdkAttributes: (snapshot: NormalizedAttributionSnapshot) => Record<string, unknown>;
+/**
+ * Returns true if the snapshot carries any branching-relevant data beyond provider id alone.
+ */
+declare const normalizedSnapshotHasSignal: (snapshot: NormalizedAttributionSnapshot) => boolean;
+
+/**
+ * Merges two snapshots from the same session/provider layer (e.g. install + deep link).
+ * Later `overlay` wins on conflicting scalar facets; link params are shallow-merged with overlay winning per key.
+ */
+declare const mergeAttributionSnapshots: (base: NormalizedAttributionSnapshot | null, overlay: NormalizedAttributionSnapshot) => NormalizedAttributionSnapshot;
+
+/** Suggested `attribution.provider` string ids for dashboard pickers (extend as we add adapters). */
+declare const SUGGESTED_ATTRIBUTION_PROVIDER_IDS: readonly string[];
+/** Values that may appear at `attribution.confidence` after flattening. */
+declare const ATTRIBUTION_CONFIDENCE_LEVELS: readonly AttributionConfidenceLevel[];
+/** Human-readable reference for dashboard + docs (SDK decision variables). */
+declare const ATTRIBUTION_SDK_KEYS_DOC: ReadonlyArray<{
+    key: string;
+    description: string;
+}>;
+/**
+ * Catalog keys editors should offer for attribution / acquisition / deep-link branching
+ * (excludes template rows like `link.ext.<param>` — use a custom `link.ext.*` key for those).
+ */
+declare const ATTRIBUTION_PREDEFINED_DECISION_KEYS: ReadonlyArray<{
+    key: string;
+    description: string;
+}>;
+declare const isAttributionPredefinedSdkKey: (key: string) => boolean;
+declare const attributionPredefinedKeyDescription: (key: string) => string | undefined;
+
+/** Canonical prefixes for MMP / deep-link context merged into SDK attributes. */
+declare const ATTRIBUTION_CONTEXT_KEY_PREFIXES: readonly ["attribution.", "acquisition.", "link."];
+declare const sdkKeyUsesAttributionContext: (key: string) => boolean;
+declare const decisionExpressionUsesAttributionContext: (expr: DecisionExpr) => boolean;
+/** Default `next` target from the manifest entry screen (screen or decision id), or null. */
+declare const getEntryScreenDefaultJumpTarget: (manifest: FlowManifest) => string | null;
+declare const entryDefaultNextIsDecisionNode: (manifest: FlowManifest) => boolean;
+declare const decisionNodeUsesAttributionContext: (dn: DecisionNode) => boolean;
+/**
+ * True when the entry screen's default next hop is a decision node whose rules read
+ * attribution / acquisition / link SDK keys — first evaluation can run before deferred MMP data arrives.
+ */
+declare const entryDefaultNextIsAttributionDecision: (manifest: FlowManifest) => boolean;
+/** Any decision node references attribution-style SDK keys. */
+declare const manifestUsesAttributionInDecisions: (manifest: FlowManifest) => boolean;
+
+/** Bump when the persisted envelope shape changes (invalidates old cache files). */
+declare const ATTRIBUTION_CACHE_SCHEMA_VERSION = 1;
+/** Default TTL for device-side attribution fallback (24 hours). */
+declare const DEFAULT_ATTRIBUTION_CACHE_TTL_MS: number;
+/**
+ * Persisted device cache — provider-agnostic normalized snapshot + bookkeeping.
+ * Stored as JSON (e.g. AsyncStorage). Not sent to Rheo servers by default.
+ */
+declare const AttributionDeviceCacheEnvelopeSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    /** Epoch ms when this envelope was written. */
+    cachedAtMs: z.ZodNumber;
+    /** Snapshot identity — must match current adapter output shape. */
+    snapshot: z.ZodObject<{
+        providerId: z.ZodString;
+        capturedAtMs: z.ZodNumber;
+        attribution: z.ZodObject<{
+            isOrganic: z.ZodOptional<z.ZodBoolean>;
+            matchType: z.ZodOptional<z.ZodString>;
+            confidence: z.ZodOptional<z.ZodEnum<["high", "medium", "low"]>>;
+            installTimestampMs: z.ZodOptional<z.ZodNumber>;
+            clickTimestampMs: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            isOrganic?: boolean | undefined;
+            matchType?: string | undefined;
+            confidence?: "high" | "medium" | "low" | undefined;
+            installTimestampMs?: number | undefined;
+            clickTimestampMs?: number | undefined;
+        }, {
+            isOrganic?: boolean | undefined;
+            matchType?: string | undefined;
+            confidence?: "high" | "medium" | "low" | undefined;
+            installTimestampMs?: number | undefined;
+            clickTimestampMs?: number | undefined;
+        }>;
+        acquisition: z.ZodObject<{
+            source: z.ZodOptional<z.ZodString>;
+            campaign: z.ZodOptional<z.ZodString>;
+            campaignId: z.ZodOptional<z.ZodString>;
+            adset: z.ZodOptional<z.ZodString>;
+            adsetId: z.ZodOptional<z.ZodString>;
+            creative: z.ZodOptional<z.ZodString>;
+            creativeId: z.ZodOptional<z.ZodString>;
+            channel: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            source?: string | undefined;
+            campaign?: string | undefined;
+            campaignId?: string | undefined;
+            adset?: string | undefined;
+            adsetId?: string | undefined;
+            creative?: string | undefined;
+            creativeId?: string | undefined;
+            channel?: string | undefined;
+        }, {
+            source?: string | undefined;
+            campaign?: string | undefined;
+            campaignId?: string | undefined;
+            adset?: string | undefined;
+            adsetId?: string | undefined;
+            creative?: string | undefined;
+            creativeId?: string | undefined;
+            channel?: string | undefined;
+        }>;
+        link: z.ZodObject<{
+            entry: z.ZodOptional<z.ZodString>;
+            params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            params?: Record<string, string> | undefined;
+            entry?: string | undefined;
+        }, {
+            params?: Record<string, string> | undefined;
+            entry?: string | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        attribution: {
+            isOrganic?: boolean | undefined;
+            matchType?: string | undefined;
+            confidence?: "high" | "medium" | "low" | undefined;
+            installTimestampMs?: number | undefined;
+            clickTimestampMs?: number | undefined;
+        };
+        acquisition: {
+            source?: string | undefined;
+            campaign?: string | undefined;
+            campaignId?: string | undefined;
+            adset?: string | undefined;
+            adsetId?: string | undefined;
+            creative?: string | undefined;
+            creativeId?: string | undefined;
+            channel?: string | undefined;
+        };
+        link: {
+            params?: Record<string, string> | undefined;
+            entry?: string | undefined;
+        };
+        providerId: string;
+        capturedAtMs: number;
+    }, {
+        attribution: {
+            isOrganic?: boolean | undefined;
+            matchType?: string | undefined;
+            confidence?: "high" | "medium" | "low" | undefined;
+            installTimestampMs?: number | undefined;
+            clickTimestampMs?: number | undefined;
+        };
+        acquisition: {
+            source?: string | undefined;
+            campaign?: string | undefined;
+            campaignId?: string | undefined;
+            adset?: string | undefined;
+            adsetId?: string | undefined;
+            creative?: string | undefined;
+            creativeId?: string | undefined;
+            channel?: string | undefined;
+        };
+        link: {
+            params?: Record<string, string> | undefined;
+            entry?: string | undefined;
+        };
+        providerId: string;
+        capturedAtMs: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    cachedAtMs: number;
+    snapshot: {
+        attribution: {
+            isOrganic?: boolean | undefined;
+            matchType?: string | undefined;
+            confidence?: "high" | "medium" | "low" | undefined;
+            installTimestampMs?: number | undefined;
+            clickTimestampMs?: number | undefined;
+        };
+        acquisition: {
+            source?: string | undefined;
+            campaign?: string | undefined;
+            campaignId?: string | undefined;
+            adset?: string | undefined;
+            adsetId?: string | undefined;
+            creative?: string | undefined;
+            creativeId?: string | undefined;
+            channel?: string | undefined;
+        };
+        link: {
+            params?: Record<string, string> | undefined;
+            entry?: string | undefined;
+        };
+        providerId: string;
+        capturedAtMs: number;
+    };
+}, {
+    schemaVersion: 1;
+    cachedAtMs: number;
+    snapshot: {
+        attribution: {
+            isOrganic?: boolean | undefined;
+            matchType?: string | undefined;
+            confidence?: "high" | "medium" | "low" | undefined;
+            installTimestampMs?: number | undefined;
+            clickTimestampMs?: number | undefined;
+        };
+        acquisition: {
+            source?: string | undefined;
+            campaign?: string | undefined;
+            campaignId?: string | undefined;
+            adset?: string | undefined;
+            adsetId?: string | undefined;
+            creative?: string | undefined;
+            creativeId?: string | undefined;
+            channel?: string | undefined;
+        };
+        link: {
+            params?: Record<string, string> | undefined;
+            entry?: string | undefined;
+        };
+        providerId: string;
+        capturedAtMs: number;
+    };
+}>;
+type AttributionDeviceCacheEnvelope = z.infer<typeof AttributionDeviceCacheEnvelopeSchema>;
+
+declare const AttributionConfidenceSchema: z.ZodEnum<["high", "medium", "low"]>;
+
+export { ATTRIBUTION_CACHE_SCHEMA_VERSION, ATTRIBUTION_CONFIDENCE_LEVELS, ATTRIBUTION_CONTEXT_KEY_PREFIXES, ATTRIBUTION_PREDEFINED_DECISION_KEYS, ATTRIBUTION_SDK_KEYS_DOC, ATTR_KEY_ACQ_ADSET, ATTR_KEY_ACQ_ADSET_ID, ATTR_KEY_ACQ_CAMPAIGN, ATTR_KEY_ACQ_CAMPAIGN_ID, ATTR_KEY_ACQ_CHANNEL, ATTR_KEY_ACQ_CREATIVE, ATTR_KEY_ACQ_CREATIVE_ID, ATTR_KEY_ACQ_SOURCE, ATTR_KEY_CONFIDENCE, ATTR_KEY_IS_ORGANIC, ATTR_KEY_LINK_CONTENT_ID, ATTR_KEY_LINK_ENTRY, ATTR_KEY_LINK_PROMO, ATTR_KEY_LINK_REFERRAL, ATTR_KEY_MATCH_TYPE, ATTR_KEY_PROVIDER, type AcquisitionFacet, type AttributionConfidenceLevel, AttributionConfidenceSchema, type AttributionDeviceCacheEnvelope, AttributionDeviceCacheEnvelopeSchema, type AttributionFacet, type AttributionProviderId, DEFAULT_ATTRIBUTION_CACHE_TTL_MS, LINK_EXT_PREFIX, type LinkFacet, type NormalizedAttributionSnapshot, SUGGESTED_ATTRIBUTION_PROVIDER_IDS, attributionPredefinedKeyDescription, decisionExpressionUsesAttributionContext, decisionNodeUsesAttributionContext, entryDefaultNextIsAttributionDecision, entryDefaultNextIsDecisionNode, flattenAttributionSnapshotToSdkAttributes, getEntryScreenDefaultJumpTarget, isAttributionPredefinedSdkKey, manifestUsesAttributionInDecisions, mergeAttributionSnapshots, normalizedSnapshotHasSignal, sdkKeyUsesAttributionContext };

package/dist/index.js

@@ -0,0 +1,185 @@
+import { collectDecisionSdkKeys, DecisionNodeIdSchema } from '@getrheo/contracts/decisions';
+import { z } from 'zod';
+
+// src/canonicalKeys.ts
+var ATTR_KEY_PROVIDER = "attribution.provider";
+var ATTR_KEY_IS_ORGANIC = "attribution.isOrganic";
+var ATTR_KEY_CONFIDENCE = "attribution.confidence";
+var ATTR_KEY_MATCH_TYPE = "attribution.matchType";
+var ATTR_KEY_ACQ_SOURCE = "acquisition.source";
+var ATTR_KEY_ACQ_CAMPAIGN = "acquisition.campaign";
+var ATTR_KEY_ACQ_CAMPAIGN_ID = "acquisition.campaignId";
+var ATTR_KEY_ACQ_ADSET = "acquisition.adset";
+var ATTR_KEY_ACQ_ADSET_ID = "acquisition.adsetId";
+var ATTR_KEY_ACQ_CREATIVE = "acquisition.creative";
+var ATTR_KEY_ACQ_CREATIVE_ID = "acquisition.creativeId";
+var ATTR_KEY_ACQ_CHANNEL = "acquisition.channel";
+var ATTR_KEY_LINK_ENTRY = "link.entry";
+var LINK_EXT_PREFIX = "link.ext.";
+var ATTR_KEY_LINK_REFERRAL = "link.ext.referral_code";
+var ATTR_KEY_LINK_PROMO = "link.ext.promo_code";
+var ATTR_KEY_LINK_CONTENT_ID = "link.ext.content_id";
+
+// src/flatten.ts
+var sanitizeExtKey = (k) => k.replace(/[^a-zA-Z0-9_]/g, "_").slice(0, 64);
+var flattenAttributionSnapshotToSdkAttributes = (snapshot) => {
+  const out = {};
+  out[ATTR_KEY_PROVIDER] = snapshot.providerId;
+  const { attribution, acquisition, link } = snapshot;
+  if (typeof attribution.isOrganic === "boolean") {
+    out[ATTR_KEY_IS_ORGANIC] = attribution.isOrganic;
+  }
+  if (attribution.matchType !== void 0 && attribution.matchType !== "") {
+    out[ATTR_KEY_MATCH_TYPE] = attribution.matchType;
+  }
+  if (attribution.confidence !== void 0) {
+    out[ATTR_KEY_CONFIDENCE] = attribution.confidence;
+  }
+  const setStr = (key, v) => {
+    if (v !== void 0 && v !== "") out[key] = v;
+  };
+  setStr(ATTR_KEY_ACQ_SOURCE, acquisition.source);
+  setStr(ATTR_KEY_ACQ_CAMPAIGN, acquisition.campaign);
+  setStr(ATTR_KEY_ACQ_CAMPAIGN_ID, acquisition.campaignId);
+  setStr(ATTR_KEY_ACQ_ADSET, acquisition.adset);
+  setStr(ATTR_KEY_ACQ_ADSET_ID, acquisition.adsetId);
+  setStr(ATTR_KEY_ACQ_CREATIVE, acquisition.creative);
+  setStr(ATTR_KEY_ACQ_CREATIVE_ID, acquisition.creativeId);
+  setStr(ATTR_KEY_ACQ_CHANNEL, acquisition.channel);
+  setStr(ATTR_KEY_LINK_ENTRY, link.entry);
+  const params = link.params ?? {};
+  for (const [rawKey, rawVal] of Object.entries(params)) {
+    const sk = sanitizeExtKey(rawKey);
+    if (!sk) continue;
+    if (rawVal !== void 0 && rawVal !== "") {
+      out[`${LINK_EXT_PREFIX}${sk}`] = rawVal;
+    }
+  }
+  return out;
+};
+var normalizedSnapshotHasSignal = (snapshot) => {
+  const flat = flattenAttributionSnapshotToSdkAttributes(snapshot);
+  const keys = Object.keys(flat).filter((k) => k !== ATTR_KEY_PROVIDER);
+  return keys.length > 0;
+};
+
+// src/merge.ts
+var mergeAttributionSnapshots = (base, overlay) => {
+  if (!base) return overlay;
+  return {
+    providerId: overlay.providerId,
+    capturedAtMs: Math.max(base.capturedAtMs, overlay.capturedAtMs),
+    attribution: { ...base.attribution, ...overlay.attribution },
+    acquisition: { ...base.acquisition, ...overlay.acquisition },
+    link: {
+      entry: overlay.link.entry ?? base.link.entry,
+      params: { ...base.link.params, ...overlay.link.params }
+    }
+  };
+};
+
+// src/flowKeysDoc.ts
+var SUGGESTED_ATTRIBUTION_PROVIDER_IDS = [
+  "appsflyer",
+  "adjust",
+  "branch",
+  "meta",
+  "google",
+  "tiktok",
+  "snapchat",
+  "twitter"
+];
+var ATTRIBUTION_CONFIDENCE_LEVELS = [
+  "high",
+  "medium",
+  "low"
+];
+var ATTRIBUTION_SDK_KEYS_DOC = [
+  { key: ATTR_KEY_PROVIDER, description: "Which integration produced this snapshot (e.g. appsflyer)." },
+  { key: ATTR_KEY_IS_ORGANIC, description: "Organic vs non-organic (use a Boolean compare in decisions)." },
+  { key: ATTR_KEY_MATCH_TYPE, description: "Provider match type when available." },
+  { key: ATTR_KEY_CONFIDENCE, description: "Coarse confidence hint (high | medium | low)." },
+  { key: ATTR_KEY_ACQ_SOURCE, description: "Media / network / source (Meta, Google, etc.)." },
+  { key: ATTR_KEY_ACQ_CAMPAIGN, description: "Campaign name." },
+  { key: ATTR_KEY_ACQ_CAMPAIGN_ID, description: "Campaign id." },
+  { key: ATTR_KEY_ACQ_ADSET, description: "Ad set / ad group name." },
+  { key: ATTR_KEY_ACQ_ADSET_ID, description: "Ad set id." },
+  { key: ATTR_KEY_ACQ_CREATIVE, description: "Creative / ad name." },
+  { key: ATTR_KEY_ACQ_CREATIVE_ID, description: "Creative id." },
+  { key: ATTR_KEY_ACQ_CHANNEL, description: "Optional channel bucket." },
+  { key: ATTR_KEY_LINK_ENTRY, description: "Primary deep link / route value (same decision surface as campaigns)." },
+  { key: `${LINK_EXT_PREFIX}<param>`, description: "Dynamic link parameters (e.g. link.ext.promo_code)." },
+  { key: ATTR_KEY_LINK_REFERRAL, description: "Example: mapped referral code param." },
+  { key: ATTR_KEY_LINK_PROMO, description: "Example: mapped promo code param." },
+  { key: ATTR_KEY_LINK_CONTENT_ID, description: "Example: mapped content id param." }
+];
+var ATTRIBUTION_PREDEFINED_DECISION_KEYS = ATTRIBUTION_SDK_KEYS_DOC.filter((row) => !row.key.includes("<"));
+var ATTRIBUTION_PREDEFINED_SDK_KEY_SET = new Set(
+  ATTRIBUTION_PREDEFINED_DECISION_KEYS.map((row) => row.key)
+);
+var isAttributionPredefinedSdkKey = (key) => ATTRIBUTION_PREDEFINED_SDK_KEY_SET.has(key);
+var attributionPredefinedKeyDescription = (key) => ATTRIBUTION_PREDEFINED_DECISION_KEYS.find((row) => row.key === key)?.description;
+var ATTRIBUTION_CONTEXT_KEY_PREFIXES = ["attribution.", "acquisition.", "link."];
+var sdkKeyUsesAttributionContext = (key) => ATTRIBUTION_CONTEXT_KEY_PREFIXES.some((p) => key.startsWith(p));
+var decisionExpressionUsesAttributionContext = (expr) => collectDecisionSdkKeys(expr).some(sdkKeyUsesAttributionContext);
+var getEntryScreenDefaultJumpTarget = (manifest) => {
+  if (manifest.entryScreenId == null) return null;
+  const screen = manifest.screens.find((s) => s.id === manifest.entryScreenId);
+  const t = screen?.next?.default;
+  if (t == null || typeof t !== "string" || t.length === 0) return null;
+  return t;
+};
+var entryDefaultNextIsDecisionNode = (manifest) => {
+  const t = getEntryScreenDefaultJumpTarget(manifest);
+  if (!t) return false;
+  return DecisionNodeIdSchema.safeParse(t).success;
+};
+var decisionNodeUsesAttributionContext = (dn) => dn.cases.some((c) => decisionExpressionUsesAttributionContext(c.expression));
+var entryDefaultNextIsAttributionDecision = (manifest) => {
+  const t = getEntryScreenDefaultJumpTarget(manifest);
+  if (!t || !DecisionNodeIdSchema.safeParse(t).success) return false;
+  const dn = manifest.decisionNodes?.find((d) => d.id === t);
+  if (!dn) return false;
+  return decisionNodeUsesAttributionContext(dn);
+};
+var manifestUsesAttributionInDecisions = (manifest) => (manifest.decisionNodes ?? []).some(decisionNodeUsesAttributionContext);
+var AttributionConfidenceSchema = z.enum(["high", "medium", "low"]);
+
+// src/cacheEnvelope.ts
+var ATTRIBUTION_CACHE_SCHEMA_VERSION = 1;
+var DEFAULT_ATTRIBUTION_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var AttributionDeviceCacheEnvelopeSchema = z.object({
+  schemaVersion: z.literal(ATTRIBUTION_CACHE_SCHEMA_VERSION),
+  /** Epoch ms when this envelope was written. */
+  cachedAtMs: z.number(),
+  /** Snapshot identity — must match current adapter output shape. */
+  snapshot: z.object({
+    providerId: z.string().min(1),
+    capturedAtMs: z.number(),
+    attribution: z.object({
+      isOrganic: z.boolean().optional(),
+      matchType: z.string().optional(),
+      confidence: AttributionConfidenceSchema.optional(),
+      installTimestampMs: z.number().optional(),
+      clickTimestampMs: z.number().optional()
+    }),
+    acquisition: z.object({
+      source: z.string().optional(),
+      campaign: z.string().optional(),
+      campaignId: z.string().optional(),
+      adset: z.string().optional(),
+      adsetId: z.string().optional(),
+      creative: z.string().optional(),
+      creativeId: z.string().optional(),
+      channel: z.string().optional()
+    }),
+    link: z.object({
+      entry: z.string().optional(),
+      params: z.record(z.string(), z.string()).optional()
+    })
+  })
+});
+
+export { ATTRIBUTION_CACHE_SCHEMA_VERSION, ATTRIBUTION_CONFIDENCE_LEVELS, ATTRIBUTION_CONTEXT_KEY_PREFIXES, ATTRIBUTION_PREDEFINED_DECISION_KEYS, ATTRIBUTION_SDK_KEYS_DOC, ATTR_KEY_ACQ_ADSET, ATTR_KEY_ACQ_ADSET_ID, ATTR_KEY_ACQ_CAMPAIGN, ATTR_KEY_ACQ_CAMPAIGN_ID, ATTR_KEY_ACQ_CHANNEL, ATTR_KEY_ACQ_CREATIVE, ATTR_KEY_ACQ_CREATIVE_ID, ATTR_KEY_ACQ_SOURCE, ATTR_KEY_CONFIDENCE, ATTR_KEY_IS_ORGANIC, ATTR_KEY_LINK_CONTENT_ID, ATTR_KEY_LINK_ENTRY, ATTR_KEY_LINK_PROMO, ATTR_KEY_LINK_REFERRAL, ATTR_KEY_MATCH_TYPE, ATTR_KEY_PROVIDER, AttributionConfidenceSchema, AttributionDeviceCacheEnvelopeSchema, DEFAULT_ATTRIBUTION_CACHE_TTL_MS, LINK_EXT_PREFIX, SUGGESTED_ATTRIBUTION_PROVIDER_IDS, attributionPredefinedKeyDescription, decisionExpressionUsesAttributionContext, decisionNodeUsesAttributionContext, entryDefaultNextIsAttributionDecision, entryDefaultNextIsDecisionNode, flattenAttributionSnapshotToSdkAttributes, getEntryScreenDefaultJumpTarget, isAttributionPredefinedSdkKey, manifestUsesAttributionInDecisions, mergeAttributionSnapshots, normalizedSnapshotHasSignal, sdkKeyUsesAttributionContext };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/canonicalKeys.ts","../src/flatten.ts","../src/merge.ts","../src/flowKeysDoc.ts","../src/builderHints.ts","../src/zodTypes.ts","../src/cacheEnvelope.ts"],"names":["z"],"mappings":";;;;AASO,IAAM,iBAAA,GAAoB;AAG1B,IAAM,mBAAA,GAAsB;AAG5B,IAAM,mBAAA,GAAsB;AAG5B,IAAM,mBAAA,GAAsB;AAG5B,IAAM,mBAAA,GAAsB;AAE5B,IAAM,qBAAA,GAAwB;AAC9B,IAAM,wBAAA,GAA2B;AACjC,IAAM,kBAAA,GAAqB;AAC3B,IAAM,qBAAA,GAAwB;AAC9B,IAAM,qBAAA,GAAwB;AAC9B,IAAM,wBAAA,GAA2B;AAGjC,IAAM,oBAAA,GAAuB;AAM7B,IAAM,mBAAA,GAAsB;AAM5B,IAAM,eAAA,GAAkB;AAGxB,IAAM,sBAAA,GAAyB;AAC/B,IAAM,mBAAA,GAAsB;AAC5B,IAAM,wBAAA,GAA2B;;;AC9BxC,IAAM,cAAA,GAAiB,CAAC,CAAA,KACtB,CAAA,CAAE,OAAA,CAAQ,kBAAkB,GAAG,CAAA,CAAE,KAAA,CAAM,CAAA,EAAG,EAAE,CAAA;AAMvC,IAAM,yCAAA,GAA4C,CACvD,QAAA,KAC4B;AAC5B,EAAA,MAAM,MAA+B,EAAC;AAEtC,EAAA,GAAA,CAAI,iBAAiB,IAAI,QAAA,CAAS,UAAA;AAElC,EAAA,MAAM,EAAE,WAAA,EAAa,WAAA,EAAa,IAAA,EAAK,GAAI,QAAA;AAE3C,EAAA,IAAI,OAAO,WAAA,CAAY,SAAA,KAAc,SAAA,EAAW;AAC9C,IAAA,GAAA,CAAI,mBAAmB,IAAI,WAAA,CAAY,SAAA;AAAA,EACzC;AACA,EAAA,IAAI,WAAA,CAAY,SAAA,KAAc,MAAA,IAAa,WAAA,CAAY,cAAc,EAAA,EAAI;AACvE,IAAA,GAAA,CAAI,mBAAmB,IAAI,WAAA,CAAY,SAAA;AAAA,EACzC;AACA,EAAA,IAAI,WAAA,CAAY,eAAe,MAAA,EAAW;AACxC,IAAA,GAAA,CAAI,mBAAmB,IAAI,WAAA,CAAY,UAAA;AAAA,EACzC;AAEA,EAAA,MAAM,MAAA,GAAS,CAAC,GAAA,EAAa,CAAA,KAAqB;AAChD,IAAA,IAAI,MAAM,MAAA,IAAa,CAAA,KAAM,EAAA,EAAI,GAAA,CAAI,GAAG,CAAA,GAAI,CAAA;AAAA,EAC9C,CAAA;AAEA,EAAA,MAAA,CAAO,mBAAA,EAAqB,YAAY,MAAM,CAAA;AAC9C,EAAA,MAAA,CAAO,qBAAA,EAAuB,YAAY,QAAQ,CAAA;AAClD,EAAA,MAAA,CAAO,wBAAA,EAA0B,YAAY,UAAU,CAAA;AACvD,EAAA,MAAA,CAAO,kBAAA,EAAoB,YAAY,KAAK,CAAA;AAC5C,EAAA,MAAA,CAAO,qBAAA,EAAuB,YAAY,OAAO,CAAA;AACjD,EAAA,MAAA,CAAO,qBAAA,EAAuB,YAAY,QAAQ,CAAA;AAClD,EAAA,MAAA,CAAO,wBAAA,EAA0B,YAAY,UAAU,CAAA;AACvD,EAAA,MAAA,CAAO,oBAAA,EAAsB,YAAY,OAAO,CAAA;AAEhD,EAAA,MAAA,CAAO,mBAAA,EAAqB,KAAK,KAAK,CAAA;AAEtC,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,MAAA,IAAU,EAAC;AAC/B,EAAA,KAAA,MAAW,CAAC,MAAA,EAAQ,MAAM,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAAG;AACrD,IAAA,MAAM,EAAA,GAAK,eAAe,MAAM,CAAA;AAChC,IAAA,IAAI,CAAC,EAAA,EAAI;AACT,IAAA,IAAI,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,EAAA,EAAI;AACzC,MAAA,GAAA,CAAI,CAAA,EAAG,eAAe,CAAA,EAAG,EAAE,EAAE,CAAA,GAAI,MAAA;AAAA,IACnC;AAAA,EACF;AAEA,EAAA,OAAO,GAAA;AACT;AAKO,IAAM,2BAAA,GAA8B,CAAC,QAAA,KAAqD;AAC/F,EAAA,MAAM,IAAA,GAAO,0CAA0C,QAAQ,CAAA;AAC/D,EAAA,MAAM,IAAA,GAAO,OAAO,IAAA,CAAK,IAAI,EAAE,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,KAAM,iBAAiB,CAAA;AACpE,EAAA,OAAO,KAAK,MAAA,GAAS,CAAA;AACvB;;;ACxEO,IAAM,yBAAA,GAA4B,CACvC,IAAA,EACA,OAAA,KACkC;AAClC,EAAA,IAAI,CAAC,MAAM,OAAO,OAAA;AAClB,EAAA,OAAO;AAAA,IACL,YAAY,OAAA,CAAQ,UAAA;AAAA,IACpB,cAAc,IAAA,CAAK,GAAA,CAAI,IAAA,CAAK,YAAA,EAAc,QAAQ,YAAY,CAAA;AAAA,IAC9D,aAAa,EAAE,GAAG,KAAK,WAAA,EAAa,GAAG,QAAQ,WAAA,EAAY;AAAA,IAC3D,aAAa,EAAE,GAAG,KAAK,WAAA,EAAa,GAAG,QAAQ,WAAA,EAAY;AAAA,IAC3D,IAAA,EAAM;AAAA,MACJ,KAAA,EAAO,OAAA,CAAQ,IAAA,CAAK,KAAA,IAAS,KAAK,IAAA,CAAK,KAAA;AAAA,MACvC,MAAA,EAAQ,EAAE,GAAG,IAAA,CAAK,KAAK,MAAA,EAAQ,GAAG,OAAA,CAAQ,IAAA,CAAK,MAAA;AAAO;AACxD,GACF;AACF;;;ACCO,IAAM,kCAAA,GAAwD;AAAA,EACnE,WAAA;AAAA,EACA,QAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EACA,QAAA;AAAA,EACA,QAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF;AAGO,IAAM,6BAAA,GAAuE;AAAA,EAClF,MAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF;AAGO,IAAM,wBAAA,GAAgF;AAAA,EAC3F,EAAE,GAAA,EAAK,iBAAA,EAAmB,WAAA,EAAa,4DAAA,EAA6D;AAAA,EACpG,EAAE,GAAA,EAAK,mBAAA,EAAqB,WAAA,EAAa,8DAAA,EAA+D;AAAA,EACxG,EAAE,GAAA,EAAK,mBAAA,EAAqB,WAAA,EAAa,qCAAA,EAAsC;AAAA,EAC/E,EAAE,GAAA,EAAK,mBAAA,EAAqB,WAAA,EAAa,+CAAA,EAAgD;AAAA,EACzF,EAAE,GAAA,EAAK,mBAAA,EAAqB,WAAA,EAAa,gDAAA,EAAiD;AAAA,EAC1F,EAAE,GAAA,EAAK,qBAAA,EAAuB,WAAA,EAAa,gBAAA,EAAiB;AAAA,EAC5D,EAAE,GAAA,EAAK,wBAAA,EAA0B,WAAA,EAAa,cAAA,EAAe;AAAA,EAC7D,EAAE,GAAA,EAAK,kBAAA,EAAoB,WAAA,EAAa,yBAAA,EAA0B;AAAA,EAClE,EAAE,GAAA,EAAK,qBAAA,EAAuB,WAAA,EAAa,YAAA,EAAa;AAAA,EACxD,EAAE,GAAA,EAAK,qBAAA,EAAuB,WAAA,EAAa,qBAAA,EAAsB;AAAA,EACjE,EAAE,GAAA,EAAK,wBAAA,EAA0B,WAAA,EAAa,cAAA,EAAe;AAAA,EAC7D,EAAE,GAAA,EAAK,oBAAA,EAAsB,WAAA,EAAa,0BAAA,EAA2B;AAAA,EACrE,EAAE,GAAA,EAAK,mBAAA,EAAqB,WAAA,EAAa,uEAAA,EAAwE;AAAA,EACjH,EAAE,GAAA,EAAK,CAAA,EAAG,eAAe,CAAA,OAAA,CAAA,EAAW,aAAa,qDAAA,EAAsD;AAAA,EACvG,EAAE,GAAA,EAAK,sBAAA,EAAwB,WAAA,EAAa,sCAAA,EAAuC;AAAA,EACnF,EAAE,GAAA,EAAK,mBAAA,EAAqB,WAAA,EAAa,mCAAA,EAAoC;AAAA,EAC7E,EAAE,GAAA,EAAK,wBAAA,EAA0B,WAAA,EAAa,mCAAA;AAChD;AAMO,IAAM,oCAAA,GAGR,wBAAA,CAAyB,MAAA,CAAO,CAAC,GAAA,KAAQ,CAAC,GAAA,CAAI,GAAA,CAAI,QAAA,CAAS,GAAG,CAAC;AAEpE,IAAM,qCAA0D,IAAI,GAAA;AAAA,EAClE,oCAAA,CAAqC,GAAA,CAAI,CAAC,GAAA,KAAQ,IAAI,GAAG;AAC3D,CAAA;AAEO,IAAM,6BAAA,GAAgC,CAAC,GAAA,KAC5C,kCAAA,CAAmC,IAAI,GAAG;AAErC,IAAM,mCAAA,GAAsC,CAAC,GAAA,KAClD,oCAAA,CAAqC,IAAA,CAAK,CAAC,GAAA,KAAQ,GAAA,CAAI,GAAA,KAAQ,GAAG,CAAA,EAAG;ACrEhE,IAAM,gCAAA,GAAmC,CAAC,cAAA,EAAgB,cAAA,EAAgB,OAAO;AAEjF,IAAM,4BAAA,GAA+B,CAAC,GAAA,KAC3C,gCAAA,CAAiC,IAAA,CAAK,CAAC,CAAA,KAAM,GAAA,CAAI,UAAA,CAAW,CAAC,CAAC;AAEzD,IAAM,2CAA2C,CAAC,IAAA,KACvD,uBAAuB,IAAI,CAAA,CAAE,KAAK,4BAA4B;AAGzD,IAAM,+BAAA,GAAkC,CAAC,QAAA,KAA0C;AACxF,EAAA,IAAI,QAAA,CAAS,aAAA,IAAiB,IAAA,EAAM,OAAO,IAAA;AAC3C,EAAA,MAAM,MAAA,GAAS,SAAS,OAAA,CAAQ,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,EAAA,KAAO,QAAA,CAAS,aAAa,CAAA;AAC3E,EAAA,MAAM,CAAA,GAAI,QAAQ,IAAA,EAAM,OAAA;AACxB,EAAA,IAAI,CAAA,IAAK,QAAQ,OAAO,CAAA,KAAM,YAAY,CAAA,CAAE,MAAA,KAAW,GAAG,OAAO,IAAA;AACjE,EAAA,OAAO,CAAA;AACT;AAEO,IAAM,8BAAA,GAAiC,CAAC,QAAA,KAAoC;AACjF,EAAA,MAAM,CAAA,GAAI,gCAAgC,QAAQ,CAAA;AAClD,EAAA,IAAI,CAAC,GAAG,OAAO,KAAA;AACf,EAAA,OAAO,oBAAA,CAAqB,SAAA,CAAU,CAAC,CAAA,CAAE,OAAA;AAC3C;AAEO,IAAM,kCAAA,GAAqC,CAAC,EAAA,KACjD,EAAA,CAAG,KAAA,CAAM,IAAA,CAAK,CAAC,CAAA,KAAM,wCAAA,CAAyC,CAAA,CAAE,UAAU,CAAC;AAMtE,IAAM,qCAAA,GAAwC,CAAC,QAAA,KAAoC;AACxF,EAAA,MAAM,CAAA,GAAI,gCAAgC,QAAQ,CAAA;AAClD,EAAA,IAAI,CAAC,KAAK,CAAC,oBAAA,CAAqB,UAAU,CAAC,CAAA,CAAE,SAAS,OAAO,KAAA;AAC7D,EAAA,MAAM,EAAA,GAAK,SAAS,aAAA,EAAe,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,CAAC,CAAA;AACzD,EAAA,IAAI,CAAC,IAAI,OAAO,KAAA;AAChB,EAAA,OAAO,mCAAmC,EAAE,CAAA;AAC9C;AAGO,IAAM,kCAAA,GAAqC,CAAC,QAAA,KAAA,CAChD,QAAA,CAAS,iBAAiB,EAAC,EAAG,KAAK,kCAAkC;AC/CjE,IAAM,8BAA8B,CAAA,CAAE,IAAA,CAAK,CAAC,MAAA,EAAQ,QAAA,EAAU,KAAK,CAAC;;;ACEpE,IAAM,gCAAA,GAAmC;AAGzC,IAAM,gCAAA,GAAmC,EAAA,GAAK,EAAA,GAAK,EAAA,GAAK;AAMxD,IAAM,oCAAA,GAAuCA,EAAE,MAAA,CAAO;AAAA,EAC3D,aAAA,EAAeA,CAAAA,CAAE,OAAA,CAAQ,gCAAgC,CAAA;AAAA;AAAA,EAEzD,UAAA,EAAYA,EAAE,MAAA,EAAO;AAAA;AAAA,EAErB,QAAA,EAAUA,EAAE,MAAA,CAAO;AAAA,IACjB,UAAA,EAAYA,CAAAA,CAAE,MAAA,EAAO,CAAE,IAAI,CAAC,CAAA;AAAA,IAC5B,YAAA,EAAcA,EAAE,MAAA,EAAO;AAAA,IACvB,WAAA,EAAaA,EAAE,MAAA,CAAO;AAAA,MACpB,SAAA,EAAWA,CAAAA,CAAE,OAAA,EAAQ,CAAE,QAAA,EAAS;AAAA,MAChC,SAAA,EAAWA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MAC/B,UAAA,EAAY,4BAA4B,QAAA,EAAS;AAAA,MACjD,kBAAA,EAAoBA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MACxC,gBAAA,EAAkBA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA;AAAS,KACvC,CAAA;AAAA,IACD,WAAA,EAAaA,EAAE,MAAA,CAAO;AAAA,MACpB,MAAA,EAAQA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MAC5B,QAAA,EAAUA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MAC9B,UAAA,EAAYA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MAChC,KAAA,EAAOA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MAC3B,OAAA,EAASA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MAC7B,QAAA,EAAUA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MAC9B,UAAA,EAAYA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MAChC,OAAA,EAASA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA;AAAS,KAC9B,CAAA;AAAA,IACD,IAAA,EAAMA,EAAE,MAAA,CAAO;AAAA,MACb,KAAA,EAAOA,CAAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA,MAC3B,MAAA,EAAQA,CAAAA,CAAE,MAAA,CAAOA,CAAAA,CAAE,MAAA,IAAUA,CAAAA,CAAE,MAAA,EAAQ,CAAA,CAAE,QAAA;AAAS,KACnD;AAAA,GACF;AACH,CAAC","file":"index.js","sourcesContent":["/**\n * Universal SDK attribute keys for mobile attribution / deep-link context.\n * Provider adapters (AppsFlyer, Adjust, …) map native payloads → these names.\n *\n * Host-supplied `sdkAttributes` should avoid these prefixes to prevent clashes:\n * `attribution.`, `acquisition.`, `link.`\n */\n\n/** Metadata about which MMP / SDK produced the current snapshot (string id, e.g. `appsflyer`). */\nexport const ATTR_KEY_PROVIDER = 'attribution.provider' as const;\n\n/** Whether the install/open was classified as organic (`boolean` in decision eval). */\nexport const ATTR_KEY_IS_ORGANIC = 'attribution.isOrganic' as const;\n\n/** Optional coarse confidence hint from the provider (`high` | `medium` | `low`). */\nexport const ATTR_KEY_CONFIDENCE = 'attribution.confidence' as const;\n\n/** Provider-specific match type string when available (probabilistic, etc.). */\nexport const ATTR_KEY_MATCH_TYPE = 'attribution.matchType' as const;\n\n/** Media / network / channel — paid ads, social, search, etc. */\nexport const ATTR_KEY_ACQ_SOURCE = 'acquisition.source' as const;\n\nexport const ATTR_KEY_ACQ_CAMPAIGN = 'acquisition.campaign' as const;\nexport const ATTR_KEY_ACQ_CAMPAIGN_ID = 'acquisition.campaignId' as const;\nexport const ATTR_KEY_ACQ_ADSET = 'acquisition.adset' as const;\nexport const ATTR_KEY_ACQ_ADSET_ID = 'acquisition.adsetId' as const;\nexport const ATTR_KEY_ACQ_CREATIVE = 'acquisition.creative' as const;\nexport const ATTR_KEY_ACQ_CREATIVE_ID = 'acquisition.creativeId' as const;\n\n/** Optional coarse channel bucket (e.g. social, search). */\nexport const ATTR_KEY_ACQ_CHANNEL = 'acquisition.channel' as const;\n\n/**\n * Primary entry identifier from a universal / deep link — same decision surface as campaigns.\n * Semantic: “what route or offer this open represents”.\n */\nexport const ATTR_KEY_LINK_ENTRY = 'link.entry' as const;\n\n/**\n * Flattened dynamic params from links / deferred payloads.\n * Pattern: `link.ext.<paramKey>` where paramKey is provider-normalized (alphanumeric + underscore).\n */\nexport const LINK_EXT_PREFIX = 'link.ext.' as const;\n\n/** Well-known link.param keys (optional convenience aliases providers may map). */\nexport const ATTR_KEY_LINK_REFERRAL = 'link.ext.referral_code' as const;\nexport const ATTR_KEY_LINK_PROMO = 'link.ext.promo_code' as const;\nexport const ATTR_KEY_LINK_CONTENT_ID = 'link.ext.content_id' as const;\n","import {\n  ATTR_KEY_ACQ_ADSET,\n  ATTR_KEY_ACQ_ADSET_ID,\n  ATTR_KEY_ACQ_CAMPAIGN,\n  ATTR_KEY_ACQ_CAMPAIGN_ID,\n  ATTR_KEY_ACQ_CHANNEL,\n  ATTR_KEY_ACQ_CREATIVE,\n  ATTR_KEY_ACQ_CREATIVE_ID,\n  ATTR_KEY_ACQ_SOURCE,\n  ATTR_KEY_CONFIDENCE,\n  ATTR_KEY_IS_ORGANIC,\n  ATTR_KEY_LINK_ENTRY,\n  ATTR_KEY_MATCH_TYPE,\n  ATTR_KEY_PROVIDER,\n  LINK_EXT_PREFIX,\n} from './canonicalKeys';\nimport type { NormalizedAttributionSnapshot } from './types';\n\nconst sanitizeExtKey = (k: string): string =>\n  k.replace(/[^a-zA-Z0-9_]/g, '_').slice(0, 64);\n\n/**\n * Maps a normalized snapshot into flat `sdkAttributes` entries for decision nodes.\n * Omits undefined leaves; booleans stay booleans for boolean predicates.\n */\nexport const flattenAttributionSnapshotToSdkAttributes = (\n  snapshot: NormalizedAttributionSnapshot,\n): Record<string, unknown> => {\n  const out: Record<string, unknown> = {};\n\n  out[ATTR_KEY_PROVIDER] = snapshot.providerId;\n\n  const { attribution, acquisition, link } = snapshot;\n\n  if (typeof attribution.isOrganic === 'boolean') {\n    out[ATTR_KEY_IS_ORGANIC] = attribution.isOrganic;\n  }\n  if (attribution.matchType !== undefined && attribution.matchType !== '') {\n    out[ATTR_KEY_MATCH_TYPE] = attribution.matchType;\n  }\n  if (attribution.confidence !== undefined) {\n    out[ATTR_KEY_CONFIDENCE] = attribution.confidence;\n  }\n\n  const setStr = (key: string, v?: string): void => {\n    if (v !== undefined && v !== '') out[key] = v;\n  };\n\n  setStr(ATTR_KEY_ACQ_SOURCE, acquisition.source);\n  setStr(ATTR_KEY_ACQ_CAMPAIGN, acquisition.campaign);\n  setStr(ATTR_KEY_ACQ_CAMPAIGN_ID, acquisition.campaignId);\n  setStr(ATTR_KEY_ACQ_ADSET, acquisition.adset);\n  setStr(ATTR_KEY_ACQ_ADSET_ID, acquisition.adsetId);\n  setStr(ATTR_KEY_ACQ_CREATIVE, acquisition.creative);\n  setStr(ATTR_KEY_ACQ_CREATIVE_ID, acquisition.creativeId);\n  setStr(ATTR_KEY_ACQ_CHANNEL, acquisition.channel);\n\n  setStr(ATTR_KEY_LINK_ENTRY, link.entry);\n\n  const params = link.params ?? {};\n  for (const [rawKey, rawVal] of Object.entries(params)) {\n    const sk = sanitizeExtKey(rawKey);\n    if (!sk) continue;\n    if (rawVal !== undefined && rawVal !== '') {\n      out[`${LINK_EXT_PREFIX}${sk}`] = rawVal;\n    }\n  }\n\n  return out;\n};\n\n/**\n * Returns true if the snapshot carries any branching-relevant data beyond provider id alone.\n */\nexport const normalizedSnapshotHasSignal = (snapshot: NormalizedAttributionSnapshot): boolean => {\n  const flat = flattenAttributionSnapshotToSdkAttributes(snapshot);\n  const keys = Object.keys(flat).filter((k) => k !== ATTR_KEY_PROVIDER);\n  return keys.length > 0;\n};\n","import type { NormalizedAttributionSnapshot } from './types';\n\n/**\n * Merges two snapshots from the same session/provider layer (e.g. install + deep link).\n * Later `overlay` wins on conflicting scalar facets; link params are shallow-merged with overlay winning per key.\n */\nexport const mergeAttributionSnapshots = (\n  base: NormalizedAttributionSnapshot | null,\n  overlay: NormalizedAttributionSnapshot,\n): NormalizedAttributionSnapshot => {\n  if (!base) return overlay;\n  return {\n    providerId: overlay.providerId,\n    capturedAtMs: Math.max(base.capturedAtMs, overlay.capturedAtMs),\n    attribution: { ...base.attribution, ...overlay.attribution },\n    acquisition: { ...base.acquisition, ...overlay.acquisition },\n    link: {\n      entry: overlay.link.entry ?? base.link.entry,\n      params: { ...base.link.params, ...overlay.link.params },\n    },\n  };\n};\n","import {\n  ATTR_KEY_ACQ_ADSET,\n  ATTR_KEY_ACQ_ADSET_ID,\n  ATTR_KEY_ACQ_CAMPAIGN,\n  ATTR_KEY_ACQ_CAMPAIGN_ID,\n  ATTR_KEY_ACQ_CHANNEL,\n  ATTR_KEY_ACQ_CREATIVE,\n  ATTR_KEY_ACQ_CREATIVE_ID,\n  ATTR_KEY_ACQ_SOURCE,\n  ATTR_KEY_CONFIDENCE,\n  ATTR_KEY_IS_ORGANIC,\n  ATTR_KEY_LINK_CONTENT_ID,\n  ATTR_KEY_LINK_ENTRY,\n  ATTR_KEY_LINK_PROMO,\n  ATTR_KEY_LINK_REFERRAL,\n  ATTR_KEY_MATCH_TYPE,\n  ATTR_KEY_PROVIDER,\n  LINK_EXT_PREFIX,\n} from './canonicalKeys';\nimport type { AttributionConfidenceLevel } from './types';\n\n/** Suggested `attribution.provider` string ids for dashboard pickers (extend as we add adapters). */\nexport const SUGGESTED_ATTRIBUTION_PROVIDER_IDS: readonly string[] = [\n  'appsflyer',\n  'adjust',\n  'branch',\n  'meta',\n  'google',\n  'tiktok',\n  'snapchat',\n  'twitter',\n];\n\n/** Values that may appear at `attribution.confidence` after flattening. */\nexport const ATTRIBUTION_CONFIDENCE_LEVELS: readonly AttributionConfidenceLevel[] = [\n  'high',\n  'medium',\n  'low',\n];\n\n/** Human-readable reference for dashboard + docs (SDK decision variables). */\nexport const ATTRIBUTION_SDK_KEYS_DOC: ReadonlyArray<{ key: string; description: string }> = [\n  { key: ATTR_KEY_PROVIDER, description: 'Which integration produced this snapshot (e.g. appsflyer).' },\n  { key: ATTR_KEY_IS_ORGANIC, description: 'Organic vs non-organic (use a Boolean compare in decisions).' },\n  { key: ATTR_KEY_MATCH_TYPE, description: 'Provider match type when available.' },\n  { key: ATTR_KEY_CONFIDENCE, description: 'Coarse confidence hint (high | medium | low).' },\n  { key: ATTR_KEY_ACQ_SOURCE, description: 'Media / network / source (Meta, Google, etc.).' },\n  { key: ATTR_KEY_ACQ_CAMPAIGN, description: 'Campaign name.' },\n  { key: ATTR_KEY_ACQ_CAMPAIGN_ID, description: 'Campaign id.' },\n  { key: ATTR_KEY_ACQ_ADSET, description: 'Ad set / ad group name.' },\n  { key: ATTR_KEY_ACQ_ADSET_ID, description: 'Ad set id.' },\n  { key: ATTR_KEY_ACQ_CREATIVE, description: 'Creative / ad name.' },\n  { key: ATTR_KEY_ACQ_CREATIVE_ID, description: 'Creative id.' },\n  { key: ATTR_KEY_ACQ_CHANNEL, description: 'Optional channel bucket.' },\n  { key: ATTR_KEY_LINK_ENTRY, description: 'Primary deep link / route value (same decision surface as campaigns).' },\n  { key: `${LINK_EXT_PREFIX}<param>`, description: 'Dynamic link parameters (e.g. link.ext.promo_code).' },\n  { key: ATTR_KEY_LINK_REFERRAL, description: 'Example: mapped referral code param.' },\n  { key: ATTR_KEY_LINK_PROMO, description: 'Example: mapped promo code param.' },\n  { key: ATTR_KEY_LINK_CONTENT_ID, description: 'Example: mapped content id param.' },\n];\n\n/**\n * Catalog keys editors should offer for attribution / acquisition / deep-link branching\n * (excludes template rows like `link.ext.<param>` — use a custom `link.ext.*` key for those).\n */\nexport const ATTRIBUTION_PREDEFINED_DECISION_KEYS: ReadonlyArray<{\n  key: string;\n  description: string;\n}> = ATTRIBUTION_SDK_KEYS_DOC.filter((row) => !row.key.includes('<'));\n\nconst ATTRIBUTION_PREDEFINED_SDK_KEY_SET: ReadonlySet<string> = new Set(\n  ATTRIBUTION_PREDEFINED_DECISION_KEYS.map((row) => row.key),\n);\n\nexport const isAttributionPredefinedSdkKey = (key: string): boolean =>\n  ATTRIBUTION_PREDEFINED_SDK_KEY_SET.has(key);\n\nexport const attributionPredefinedKeyDescription = (key: string): string | undefined =>\n  ATTRIBUTION_PREDEFINED_DECISION_KEYS.find((row) => row.key === key)?.description;\n","import type { FlowManifest } from '@getrheo/contracts/manifest';\nimport {\n  collectDecisionSdkKeys,\n  DecisionNodeIdSchema,\n  type DecisionExpr,\n  type DecisionNode,\n} from '@getrheo/contracts/decisions';\n\n/** Canonical prefixes for MMP / deep-link context merged into SDK attributes. */\nexport const ATTRIBUTION_CONTEXT_KEY_PREFIXES = ['attribution.', 'acquisition.', 'link.'] as const;\n\nexport const sdkKeyUsesAttributionContext = (key: string): boolean =>\n  ATTRIBUTION_CONTEXT_KEY_PREFIXES.some((p) => key.startsWith(p));\n\nexport const decisionExpressionUsesAttributionContext = (expr: DecisionExpr): boolean =>\n  collectDecisionSdkKeys(expr).some(sdkKeyUsesAttributionContext);\n\n/** Default `next` target from the manifest entry screen (screen or decision id), or null. */\nexport const getEntryScreenDefaultJumpTarget = (manifest: FlowManifest): string | null => {\n  if (manifest.entryScreenId == null) return null;\n  const screen = manifest.screens.find((s) => s.id === manifest.entryScreenId);\n  const t = screen?.next?.default;\n  if (t == null || typeof t !== 'string' || t.length === 0) return null;\n  return t;\n};\n\nexport const entryDefaultNextIsDecisionNode = (manifest: FlowManifest): boolean => {\n  const t = getEntryScreenDefaultJumpTarget(manifest);\n  if (!t) return false;\n  return DecisionNodeIdSchema.safeParse(t).success;\n};\n\nexport const decisionNodeUsesAttributionContext = (dn: DecisionNode): boolean =>\n  dn.cases.some((c) => decisionExpressionUsesAttributionContext(c.expression));\n\n/**\n * True when the entry screen's default next hop is a decision node whose rules read\n * attribution / acquisition / link SDK keys — first evaluation can run before deferred MMP data arrives.\n */\nexport const entryDefaultNextIsAttributionDecision = (manifest: FlowManifest): boolean => {\n  const t = getEntryScreenDefaultJumpTarget(manifest);\n  if (!t || !DecisionNodeIdSchema.safeParse(t).success) return false;\n  const dn = manifest.decisionNodes?.find((d) => d.id === t);\n  if (!dn) return false;\n  return decisionNodeUsesAttributionContext(dn);\n};\n\n/** Any decision node references attribution-style SDK keys. */\nexport const manifestUsesAttributionInDecisions = (manifest: FlowManifest): boolean =>\n  (manifest.decisionNodes ?? []).some(decisionNodeUsesAttributionContext);\n","import { z } from 'zod';\n\nexport const AttributionConfidenceSchema = z.enum(['high', 'medium', 'low']);\n","import { z } from 'zod';\nimport { AttributionConfidenceSchema } from './zodTypes';\n\n/** Bump when the persisted envelope shape changes (invalidates old cache files). */\nexport const ATTRIBUTION_CACHE_SCHEMA_VERSION = 1;\n\n/** Default TTL for device-side attribution fallback (24 hours). */\nexport const DEFAULT_ATTRIBUTION_CACHE_TTL_MS = 24 * 60 * 60 * 1000;\n\n/**\n * Persisted device cache — provider-agnostic normalized snapshot + bookkeeping.\n * Stored as JSON (e.g. AsyncStorage). Not sent to Rheo servers by default.\n */\nexport const AttributionDeviceCacheEnvelopeSchema = z.object({\n  schemaVersion: z.literal(ATTRIBUTION_CACHE_SCHEMA_VERSION),\n  /** Epoch ms when this envelope was written. */\n  cachedAtMs: z.number(),\n  /** Snapshot identity — must match current adapter output shape. */\n  snapshot: z.object({\n    providerId: z.string().min(1),\n    capturedAtMs: z.number(),\n    attribution: z.object({\n      isOrganic: z.boolean().optional(),\n      matchType: z.string().optional(),\n      confidence: AttributionConfidenceSchema.optional(),\n      installTimestampMs: z.number().optional(),\n      clickTimestampMs: z.number().optional(),\n    }),\n    acquisition: z.object({\n      source: z.string().optional(),\n      campaign: z.string().optional(),\n      campaignId: z.string().optional(),\n      adset: z.string().optional(),\n      adsetId: z.string().optional(),\n      creative: z.string().optional(),\n      creativeId: z.string().optional(),\n      channel: z.string().optional(),\n    }),\n    link: z.object({\n      entry: z.string().optional(),\n      params: z.record(z.string(), z.string()).optional(),\n    }),\n  }),\n});\n\nexport type AttributionDeviceCacheEnvelope = z.infer<typeof AttributionDeviceCacheEnvelopeSchema>;\n"]}

package/dist/publish-exports.json

@@ -0,0 +1,6 @@
+[
+  {
+    "exportKey": ".",
+    "distFile": "./dist/index.js"
+  }
+]

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@getrheo/attribution",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.23.8",
+    "@getrheo/contracts": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.6",
+    "@rheo/config": "0.1.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/madeinusmate/onboardly.git",
+    "directory": "packages/attribution"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "node ../../scripts/build-publishable-package.mjs"
+  }
+}