@walkeros/server-transformer-fingerprint 4.7.0-next-1790245733116 → 4.7.0

package/dist/dev.d.mts

@@ -14,26 +14,10 @@ declare const SettingsSchema: z.ZodObject<{
         hourly: "hourly";
         none: "none";
     }>>;
-    ip: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        key: z.ZodOptional<z.ZodString>;
-        value: z.ZodOptional<z.ZodUnknown>;
-        fn: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>, z.ZodLiteral<false>]>>;
-    userAgent: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        key: z.ZodOptional<z.ZodString>;
-        value: z.ZodOptional<z.ZodUnknown>;
-        fn: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>, z.ZodLiteral<false>]>>;
-    site: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        key: z.ZodOptional<z.ZodString>;
-        value: z.ZodOptional<z.ZodUnknown>;
-        fn: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>, z.ZodLiteral<false>]>>;
-    fields: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        key: z.ZodOptional<z.ZodString>;
-        value: z.ZodOptional<z.ZodUnknown>;
-        fn: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>>>;
+    ip: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodLiteral<false>]>>;
+    userAgent: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodLiteral<false>]>>;
+    site: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodLiteral<false>]>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
     output: z.ZodOptional<z.ZodString>;
     length: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;

package/dist/dev.d.ts

@@ -14,26 +14,10 @@ declare const SettingsSchema: z.ZodObject<{
         hourly: "hourly";
         none: "none";
     }>>;
-    ip: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        key: z.ZodOptional<z.ZodString>;
-        value: z.ZodOptional<z.ZodUnknown>;
-        fn: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>, z.ZodLiteral<false>]>>;
-    userAgent: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        key: z.ZodOptional<z.ZodString>;
-        value: z.ZodOptional<z.ZodUnknown>;
-        fn: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>, z.ZodLiteral<false>]>>;
-    site: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        key: z.ZodOptional<z.ZodString>;
-        value: z.ZodOptional<z.ZodUnknown>;
-        fn: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>, z.ZodLiteral<false>]>>;
-    fields: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        key: z.ZodOptional<z.ZodString>;
-        value: z.ZodOptional<z.ZodUnknown>;
-        fn: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>>>;
+    ip: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodLiteral<false>]>>;
+    userAgent: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodLiteral<false>]>>;
+    site: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodLiteral<false>]>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
     output: z.ZodOptional<z.ZodString>;
     length: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;

package/dist/dev.js

@@ -1 +1 @@
-"use strict";var e,t=Object.defineProperty,i=Object.getOwnPropertyDescriptor,s=Object.getOwnPropertyNames,n=Object.prototype.hasOwnProperty,r=(e,i)=>{for(var s in i)t(e,s,{get:i[s],enumerable:!0})},a={};r(a,{examples:()=>c,hints:()=>w,schemas:()=>o}),module.exports=(e=a,((e,r,a,o)=>{if(r&&"object"==typeof r||"function"==typeof r)for(let d of s(r))n.call(e,d)||d===a||t(e,d,{get:()=>r[d],enumerable:!(o=i(r,d))||o.enumerable});return e})(t({},"__esModule",{value:!0}),e));var o={};r(o,{SettingsSchema:()=>g,settings:()=>u});var d=require("@walkeros/core/dev"),l=require("@walkeros/core/dev"),h=l.z.union([l.z.string().describe('Dot-notation path: "ingest.ip", "event.data.userId"'),l.z.object({key:l.z.string().optional().describe("Source property path"),value:l.z.unknown().optional().describe("Static value or fallback"),fn:l.z.string().optional().describe("$code: function receiving { event, ingest } that returns the value. Runs only when no key is set.")}).describe("Mapping value config for computed fields")]),p=l.z.union([h,l.z.literal(!1).describe("Switch this input off")]),g=l.z.object({salt:l.z.string().optional().describe('Secret key for the hash (HMAC), e.g. "$env.FINGERPRINT_SALT". Without it the hash can be reversed to the IP; a warning is logged.'),rotate:l.z.enum(["daily","hourly","none"]).optional().describe('Rotation window in UTC: the same visitor gets a new hash each window. Default: "daily"'),ip:p.optional().describe('Client IP, anonymized to /24 (IPv4) or /48 (IPv6) before hashing. Default: "ingest.ip" when fields is not set'),userAgent:p.optional().describe('User agent, reduced to browser, major version and OS before hashing. Default: "ingest.userAgent" when fields is not set'),site:p.optional().describe('Site the visitor is on; a URL is reduced to its hostname. Default: "event.source.url" when fields is not set'),fields:l.z.array(h).optional().describe("Extra fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }. When set, named inputs are only used if set explicitly."),output:l.z.string().optional().describe('Dot-notation path where hash is stored on the event. Default: "user.hash"'),length:l.z.number().int().positive().optional().describe("Truncate hash to this length. Default: full 64-char SHA-256 hash")}).describe("Fingerprint transformer: a cookieless, privacy-friendly visitor hash"),u=(0,d.zodToSchema)(g),c={};r(c,{step:()=>f});var f={};r(f,{ipAnonymization:()=>y,missingFields:()=>m,serverFingerprint:()=>v});var v={title:"Server fingerprint",description:'Default server fingerprint: the anonymized ingest.ip, the reduced ingest.userAgent and the site, keyed with settings.salt and rotated daily. Config: { salt: "$env.FINGERPRINT_SALT", length: 16 }. Requires source config.ingest. The hash depends on the salt and the day.',in:{name:"page view",data:{domain:"www.example.com",title:"Getting Started",id:"/docs/getting-started"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"page view",data:{domain:"www.example.com",title:"Getting Started",id:"/docs/getting-started"},user:{hash:"158f99cc06e33fd6"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}}}]]},m={public:!1,description:"Graceful handling when ingest is missing: each empty input logs one warning, and the hash is still generated.",in:{name:"session start",data:{id:"s3ss10n"},id:"ev-1700000601",trigger:"load",entity:"session",action:"start",timestamp:1700000601,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"session start",data:{id:"s3ss10n"},user:{hash:"e183220b699c10a8"},id:"ev-1700000601",trigger:"load",entity:"session",action:"start",timestamp:1700000601,source:{type:"express",platform:"server"}}}]]},y={title:"IP anonymization",description:'The ip input anonymizes the IP before hashing (IPv4 /24, IPv6 /48), so visitors from the same 10.0.42.* subnet with the same browser, major version and OS share a hash within a day. No custom fn needed. Config: { salt: "$env.FINGERPRINT_SALT", length: 16 }',in:{name:"page view",data:{domain:"www.example.com",title:"Privacy Policy",id:"/privacy"},id:"ev-1700000602",trigger:"load",entity:"page",action:"view",timestamp:1700000602,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"page view",data:{domain:"www.example.com",title:"Privacy Policy",id:"/privacy"},user:{hash:"44d9154b9a9b3792"},id:"ev-1700000602",trigger:"load",entity:"page",action:"view",timestamp:1700000602,source:{type:"express",platform:"server"}}}]]},w={"ingest-prerequisite":{text:'The default inputs ip and userAgent read ingest.ip and ingest.userAgent, so the server source must have config.ingest configured. config.ingest MUST use the map operator with direct request field paths (no req. prefix); a bare object like { ip: "req.ip" } is silently inert and leaves ingest empty. An input that resolves empty logs one warning ("Fingerprint input ... resolved empty") and the hash is still generated, but less distinct. Behind a load balancer the request ip is the balancer; read the client from headers.x-forwarded-for instead.',code:[{lang:"json",code:JSON.stringify({sources:{express:{package:"@walkeros/server-source-express",next:"fingerprint",config:{settings:{port:8080},ingest:{map:{ip:{key:"ip"},userAgent:{key:"headers.user-agent"}}}}}},transformers:{fingerprint:{package:"@walkeros/server-transformer-fingerprint",config:{settings:{salt:"$env.FINGERPRINT_SALT"}}}}},null,2)}]},"salt-and-rotation":{text:'The salt keys the hash (HMAC), so it cannot be recomputed or reversed to the IP without it. Pass it via $env so it stays out of the flow file, and use one salt per deployment. Without a salt the transformer runs but logs a warning at startup. Rotation is built in (daily by default, UTC windows): do not add a date field for it. For another window, set rotate: "none" and add the window as a field. Setting fields switches the default inputs off, so name them too: { rotate: "none", ip: "ingest.ip", userAgent: "ingest.userAgent", site: "event.source.url", fields: [{ fn: () => new Date().toISOString().slice(0, 7) }] } rotates monthly. rotate: "none" without such a field keeps one hash per visitor indefinitely, which is a privacy decision, not a default.'},"site-sources":{text:'site defaults to the hostname of event.source.url, which the walkerOS browser source sets on every event. Events without it (GA4 hits decoded by transformer-ga4, server-side events) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: "headers.origin" }), or a static { value: "example.com" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt.'},"extra-fields":{text:"fields adds values to the hash as they resolve from { event, ingest }, in order. When fields is set, the named inputs ip, userAgent and site are only used if set explicitly, so an existing fields config keeps its input set. To transform a value before hashing, use fn alone: it receives { event, ingest } and returns the value. A fn next to a key never runs. The IP never needs a custom fn: the ip input anonymizes it (IPv4 /24, IPv6 /48)."}};//# sourceMappingURL=dev.js.map
+"use strict";var e,t=Object.defineProperty,s=Object.getOwnPropertyDescriptor,i=Object.getOwnPropertyNames,n=Object.prototype.hasOwnProperty,a=(e,s)=>{for(var i in s)t(e,i,{get:s[i],enumerable:!0})},r={};a(r,{examples:()=>c,hints:()=>y,schemas:()=>o}),module.exports=(e=r,((e,a,r,o)=>{if(a&&"object"==typeof a||"function"==typeof a)for(let d of i(a))n.call(e,d)||d===r||t(e,d,{get:()=>a[d],enumerable:!(o=s(a,d))||o.enumerable});return e})(t({},"__esModule",{value:!0}),e));var o={};a(o,{SettingsSchema:()=>g,settings:()=>u});var d=require("@walkeros/core/dev"),l=require("@walkeros/core/dev"),h=l.schemas.MappingSchemas.ValueSchema,p=l.z.union([h,l.z.literal(!1).describe("Switch this input off")]),g=l.z.object({salt:l.z.string().optional().describe('Secret key for the hash (HMAC), e.g. "$env.FINGERPRINT_SALT". Without it the hash can be reversed to the IP; a warning is logged.'),rotate:l.z.enum(["daily","hourly","none"]).optional().describe('Rotation window in UTC: the same visitor gets a new hash each window. Default: "daily"'),ip:p.optional().describe('Client IP, anonymized to /24 (IPv4) or /48 (IPv6) before hashing. Default: "ingest.ip" when fields is not set'),userAgent:p.optional().describe('User agent, reduced to browser, major version and OS before hashing. Default: "ingest.userAgent" when fields is not set'),site:p.optional().describe('Site the visitor is on; a URL is reduced to its hostname. Default: "event.source.url" when fields is not set'),fields:l.z.array(h).optional().describe("Extra fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }. When set, named inputs are only used if set explicitly."),output:l.z.string().optional().describe('Dot-notation path where hash is stored on the event. Default: "user.hash"'),length:l.z.number().int().positive().optional().describe("Truncate hash to this length. Default: full 64-char SHA-256 hash")}).describe("Fingerprint transformer: a cookieless, privacy-friendly visitor hash"),u=(0,d.zodToSchema)(g),c={};a(c,{step:()=>f});var f={};a(f,{ipAnonymization:()=>w,missingFields:()=>v,serverFingerprint:()=>m});var m={title:"Server fingerprint",description:'Default server fingerprint: the anonymized ingest.ip, the reduced ingest.userAgent and the site, keyed with settings.salt and rotated daily. Config: { salt: "$env.FINGERPRINT_SALT", length: 16 }. Requires source config.ingest. The hash depends on the salt and the day.',in:{name:"page view",data:{domain:"www.example.com",title:"Getting Started",id:"/docs/getting-started"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"page view",data:{domain:"www.example.com",title:"Getting Started",id:"/docs/getting-started"},user:{hash:"158f99cc06e33fd6"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}}}]]},v={public:!1,description:"Graceful handling when ingest is missing: each empty input logs one warning, and the hash is still generated.",in:{name:"session start",data:{id:"s3ss10n"},id:"ev-1700000601",trigger:"load",entity:"session",action:"start",timestamp:1700000601,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"session start",data:{id:"s3ss10n"},user:{hash:"e183220b699c10a8"},id:"ev-1700000601",trigger:"load",entity:"session",action:"start",timestamp:1700000601,source:{type:"express",platform:"server"}}}]]},w={title:"IP anonymization",description:'The ip input anonymizes the IP before hashing (IPv4 /24, IPv6 /48), so visitors from the same 10.0.42.* subnet with the same browser, major version and OS share a hash within a day. No custom fn needed. Config: { salt: "$env.FINGERPRINT_SALT", length: 16 }',in:{name:"page view",data:{domain:"www.example.com",title:"Privacy Policy",id:"/privacy"},id:"ev-1700000602",trigger:"load",entity:"page",action:"view",timestamp:1700000602,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"page view",data:{domain:"www.example.com",title:"Privacy Policy",id:"/privacy"},user:{hash:"44d9154b9a9b3792"},id:"ev-1700000602",trigger:"load",entity:"page",action:"view",timestamp:1700000602,source:{type:"express",platform:"server"}}}]]},y={"ingest-prerequisite":{text:'The default inputs ip and userAgent read ingest.ip and ingest.userAgent, so the server source must have config.ingest configured. config.ingest MUST use the map operator with direct request field paths (no req. prefix); a bare object like { ip: "req.ip" } is silently inert and leaves ingest empty. An input that resolves empty logs one warning ("Fingerprint input ... resolved empty") and the hash is still generated, but less distinct. Behind a load balancer the request ip is the balancer; read the client from headers.x-forwarded-for instead.',code:[{lang:"json",code:JSON.stringify({sources:{express:{package:"@walkeros/server-source-express",next:"fingerprint",config:{settings:{port:8080},ingest:{map:{ip:{key:"ip"},userAgent:{key:"headers.user-agent"}}}}}},transformers:{fingerprint:{package:"@walkeros/server-transformer-fingerprint",config:{settings:{salt:"$env.FINGERPRINT_SALT"}}}}},null,2)}]},"salt-and-rotation":{text:'The salt keys the hash (HMAC), so it cannot be recomputed or reversed to the IP without it. Pass it via $env so it stays out of the flow file, and use one salt per deployment. Without a salt the transformer runs but logs a warning at startup. Rotation is built in (daily by default, UTC windows): do not add a date field for it. For another window, set rotate: "none" and add the window as a field. Setting fields switches the default inputs off, so name them too: { rotate: "none", ip: "ingest.ip", userAgent: "ingest.userAgent", site: "event.source.url", fields: [{ fn: () => new Date().toISOString().slice(0, 7) }] } rotates monthly. rotate: "none" without such a field keeps one hash per visitor indefinitely, which is a privacy decision, not a default.'},"site-sources":{text:'site defaults to the hostname of event.source.url, which the walkerOS browser and dataLayer sources set on every event and transformer-ga4 sets from the page URL of the hit (dl). Older transformer-ga4 versions did not set it, so upgrading transformer-ga4 changes the hash of GA4-decoded events once: site now joins the hash. Events without source.url (server-side events, GA4 hits without dl) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: "headers.origin" }), or a static { value: "example.com" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt.'},"extra-fields":{text:"fields adds values to the hash as they resolve from { event, ingest }, in order. When fields is set, the named inputs ip, userAgent and site are only used if set explicitly, so an existing fields config keeps its input set. To transform a value before hashing, use fn alone: it receives { event, ingest } and returns the value. A fn next to a key never runs. The IP never needs a custom fn: the ip input anonymizes it (IPv4 /24, IPv6 /48)."}};//# sourceMappingURL=dev.js.map

package/dist/dev.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/dev.ts","../src/schemas/index.ts","../src/schemas/settings.ts","../src/examples/index.ts","../src/examples/step.ts","../src/hints.ts"],"sourcesContent":["export * as schemas from './schemas';\nexport * as examples from './examples';\nexport { hints } from './hints';\n","import { zodToSchema } from '@walkeros/core/dev';\nimport { SettingsSchema } from './settings';\n\nexport { SettingsSchema, type Settings } from './settings';\nexport const settings = zodToSchema(SettingsSchema);\n","import { z } from '@walkeros/core/dev';\n\nconst FieldSchema = z.union([\n  z.string().describe('Dot-notation path: \"ingest.ip\", \"event.data.userId\"'),\n  z\n    .object({\n      key: z.string().optional().describe('Source property path'),\n      value: z.unknown().optional().describe('Static value or fallback'),\n      fn: z\n        .string()\n        .optional()\n        .describe(\n          '$code: function receiving { event, ingest } that returns the value. Runs only when no key is set.',\n        ),\n    })\n    .describe('Mapping value config for computed fields'),\n]);\n\nconst InputSchema = z.union([\n  FieldSchema,\n  z.literal(false).describe('Switch this input off'),\n]);\n\n/**\n * Fingerprint transformer settings schema.\n *\n * Mirrors: types.ts FingerprintSettings\n */\nexport const SettingsSchema = z\n  .object({\n    salt: z\n      .string()\n      .optional()\n      .describe(\n        'Secret key for the hash (HMAC), e.g. \"$env.FINGERPRINT_SALT\". Without it the hash can be reversed to the IP; a warning is logged.',\n      ),\n    rotate: z\n      .enum(['daily', 'hourly', 'none'])\n      .optional()\n      .describe(\n        'Rotation window in UTC: the same visitor gets a new hash each window. Default: \"daily\"',\n      ),\n    ip: InputSchema.optional().describe(\n      'Client IP, anonymized to /24 (IPv4) or /48 (IPv6) before hashing. Default: \"ingest.ip\" when fields is not set',\n    ),\n    userAgent: InputSchema.optional().describe(\n      'User agent, reduced to browser, major version and OS before hashing. Default: \"ingest.userAgent\" when fields is not set',\n    ),\n    site: InputSchema.optional().describe(\n      'Site the visitor is on; a URL is reduced to its hostname. Default: \"event.source.url\" when fields is not set',\n    ),\n    fields: z\n      .array(FieldSchema)\n      .optional()\n      .describe(\n        'Extra fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }. When set, named inputs are only used if set explicitly.',\n      ),\n    output: z\n      .string()\n      .optional()\n      .describe(\n        'Dot-notation path where hash is stored on the event. Default: \"user.hash\"',\n      ),\n    length: z\n      .number()\n      .int()\n      .positive()\n      .optional()\n      .describe(\n        'Truncate hash to this length. Default: full 64-char SHA-256 hash',\n      ),\n  })\n  .describe(\n    'Fingerprint transformer: a cookieless, privacy-friendly visitor hash',\n  );\n\nexport type Settings = z.infer<typeof SettingsSchema>;\n","export * as step from './step';\n","import type { Flow } from '@walkeros/core';\n\nexport const serverFingerprint: Flow.StepExample = {\n  title: 'Server fingerprint',\n  description:\n    'Default server fingerprint: the anonymized ingest.ip, the reduced ingest.userAgent and the site, keyed with settings.salt and rotated daily. ' +\n    'Config: { salt: \"$env.FINGERPRINT_SALT\", length: 16 }. Requires source config.ingest. The hash depends on the salt and the day.',\n  in: {\n    name: 'page view',\n    data: {\n      domain: 'www.example.com',\n      title: 'Getting Started',\n      id: '/docs/getting-started',\n    },\n    id: 'ev-1700000600',\n    trigger: 'load',\n    entity: 'page',\n    action: 'view',\n    timestamp: 1700000600,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'page view',\n          data: {\n            domain: 'www.example.com',\n            title: 'Getting Started',\n            id: '/docs/getting-started',\n          },\n          user: { hash: '158f99cc06e33fd6' },\n          id: 'ev-1700000600',\n          trigger: 'load',\n          entity: 'page',\n          action: 'view',\n          timestamp: 1700000600,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n\nexport const missingFields: Flow.StepExample = {\n  public: false,\n  description:\n    'Graceful handling when ingest is missing: each empty input logs one warning, and the hash is still generated.',\n  in: {\n    name: 'session start',\n    data: { id: 's3ss10n' },\n    id: 'ev-1700000601',\n    trigger: 'load',\n    entity: 'session',\n    action: 'start',\n    timestamp: 1700000601,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'session start',\n          data: { id: 's3ss10n' },\n          user: { hash: 'e183220b699c10a8' },\n          id: 'ev-1700000601',\n          trigger: 'load',\n          entity: 'session',\n          action: 'start',\n          timestamp: 1700000601,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n\nexport const ipAnonymization: Flow.StepExample = {\n  title: 'IP anonymization',\n  description:\n    'The ip input anonymizes the IP before hashing (IPv4 /24, IPv6 /48), so visitors from the same 10.0.42.* subnet ' +\n    'with the same browser, major version and OS share a hash within a day. No custom fn needed. Config: { salt: \"$env.FINGERPRINT_SALT\", length: 16 }',\n  in: {\n    name: 'page view',\n    data: {\n      domain: 'www.example.com',\n      title: 'Privacy Policy',\n      id: '/privacy',\n    },\n    id: 'ev-1700000602',\n    trigger: 'load',\n    entity: 'page',\n    action: 'view',\n    timestamp: 1700000602,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'page view',\n          data: {\n            domain: 'www.example.com',\n            title: 'Privacy Policy',\n            id: '/privacy',\n          },\n          user: { hash: '44d9154b9a9b3792' },\n          id: 'ev-1700000602',\n          trigger: 'load',\n          entity: 'page',\n          action: 'view',\n          timestamp: 1700000602,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n","import type { Hint } from '@walkeros/core';\n\nexport const hints: Hint.Hints = {\n  'ingest-prerequisite': {\n    text: 'The default inputs ip and userAgent read ingest.ip and ingest.userAgent, so the server source must have config.ingest configured. config.ingest MUST use the map operator with direct request field paths (no req. prefix); a bare object like { ip: \"req.ip\" } is silently inert and leaves ingest empty. An input that resolves empty logs one warning (\"Fingerprint input ... resolved empty\") and the hash is still generated, but less distinct. Behind a load balancer the request ip is the balancer; read the client from headers.x-forwarded-for instead.',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            sources: {\n              express: {\n                package: '@walkeros/server-source-express',\n                next: 'fingerprint',\n                config: {\n                  settings: { port: 8080 },\n                  ingest: {\n                    map: {\n                      ip: { key: 'ip' },\n                      userAgent: { key: 'headers.user-agent' },\n                    },\n                  },\n                },\n              },\n            },\n            transformers: {\n              fingerprint: {\n                package: '@walkeros/server-transformer-fingerprint',\n                config: {\n                  settings: { salt: '$env.FINGERPRINT_SALT' },\n                },\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'salt-and-rotation': {\n    text: 'The salt keys the hash (HMAC), so it cannot be recomputed or reversed to the IP without it. Pass it via $env so it stays out of the flow file, and use one salt per deployment. Without a salt the transformer runs but logs a warning at startup. Rotation is built in (daily by default, UTC windows): do not add a date field for it. For another window, set rotate: \"none\" and add the window as a field. Setting fields switches the default inputs off, so name them too: { rotate: \"none\", ip: \"ingest.ip\", userAgent: \"ingest.userAgent\", site: \"event.source.url\", fields: [{ fn: () => new Date().toISOString().slice(0, 7) }] } rotates monthly. rotate: \"none\" without such a field keeps one hash per visitor indefinitely, which is a privacy decision, not a default.',\n  },\n  'site-sources': {\n    text: 'site defaults to the hostname of event.source.url, which the walkerOS browser source sets on every event. Events without it (GA4 hits decoded by transformer-ga4, server-side events) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: \"headers.origin\" }), or a static { value: \"example.com\" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt.',\n  },\n  'extra-fields': {\n    text: 'fields adds values to the hash as they resolve from { event, ingest }, in order. When fields is set, the named inputs ip, userAgent and site are only used if set explicitly, so an existing fields config keeps its input set. To transform a value before hashing, use fn alone: it receives { event, ingest } and returns the value. A fn next to a key never runs. The IP never needs a custom fn: the ip input anonymizes it (IPv4 /24, IPv6 /48).',\n  },\n};\n"],"mappings":"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","names":["import_dev"]}
+{"version":3,"sources":["../src/dev.ts","../src/schemas/index.ts","../src/schemas/settings.ts","../src/examples/index.ts","../src/examples/step.ts","../src/hints.ts"],"sourcesContent":["export * as schemas from './schemas';\nexport * as examples from './examples';\nexport { hints } from './hints';\n","import { zodToSchema } from '@walkeros/core/dev';\nimport { SettingsSchema } from './settings';\n\nexport { SettingsSchema, type Settings } from './settings';\nexport const settings = zodToSchema(SettingsSchema);\n","import { schemas, z } from '@walkeros/core/dev';\n\n// A field or input is a Mapping.Value (a path, a constant, a value config\n// or a fallback list), resolved via getMappingValue with { event, ingest }.\nconst FieldSchema = schemas.MappingSchemas.ValueSchema;\n\nconst InputSchema = z.union([\n  FieldSchema,\n  z.literal(false).describe('Switch this input off'),\n]);\n\n/**\n * Fingerprint transformer settings schema.\n *\n * Mirrors: types.ts FingerprintSettings\n */\nexport const SettingsSchema = z\n  .object({\n    salt: z\n      .string()\n      .optional()\n      .describe(\n        'Secret key for the hash (HMAC), e.g. \"$env.FINGERPRINT_SALT\". Without it the hash can be reversed to the IP; a warning is logged.',\n      ),\n    rotate: z\n      .enum(['daily', 'hourly', 'none'])\n      .optional()\n      .describe(\n        'Rotation window in UTC: the same visitor gets a new hash each window. Default: \"daily\"',\n      ),\n    ip: InputSchema.optional().describe(\n      'Client IP, anonymized to /24 (IPv4) or /48 (IPv6) before hashing. Default: \"ingest.ip\" when fields is not set',\n    ),\n    userAgent: InputSchema.optional().describe(\n      'User agent, reduced to browser, major version and OS before hashing. Default: \"ingest.userAgent\" when fields is not set',\n    ),\n    site: InputSchema.optional().describe(\n      'Site the visitor is on; a URL is reduced to its hostname. Default: \"event.source.url\" when fields is not set',\n    ),\n    fields: z\n      .array(FieldSchema)\n      .optional()\n      .describe(\n        'Extra fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }. When set, named inputs are only used if set explicitly.',\n      ),\n    output: z\n      .string()\n      .optional()\n      .describe(\n        'Dot-notation path where hash is stored on the event. Default: \"user.hash\"',\n      ),\n    length: z\n      .number()\n      .int()\n      .positive()\n      .optional()\n      .describe(\n        'Truncate hash to this length. Default: full 64-char SHA-256 hash',\n      ),\n  })\n  .describe(\n    'Fingerprint transformer: a cookieless, privacy-friendly visitor hash',\n  );\n\nexport type Settings = z.infer<typeof SettingsSchema>;\n","export * as step from './step';\n","import type { Flow } from '@walkeros/core';\n\nexport const serverFingerprint: Flow.StepExample = {\n  title: 'Server fingerprint',\n  description:\n    'Default server fingerprint: the anonymized ingest.ip, the reduced ingest.userAgent and the site, keyed with settings.salt and rotated daily. ' +\n    'Config: { salt: \"$env.FINGERPRINT_SALT\", length: 16 }. Requires source config.ingest. The hash depends on the salt and the day.',\n  in: {\n    name: 'page view',\n    data: {\n      domain: 'www.example.com',\n      title: 'Getting Started',\n      id: '/docs/getting-started',\n    },\n    id: 'ev-1700000600',\n    trigger: 'load',\n    entity: 'page',\n    action: 'view',\n    timestamp: 1700000600,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'page view',\n          data: {\n            domain: 'www.example.com',\n            title: 'Getting Started',\n            id: '/docs/getting-started',\n          },\n          user: { hash: '158f99cc06e33fd6' },\n          id: 'ev-1700000600',\n          trigger: 'load',\n          entity: 'page',\n          action: 'view',\n          timestamp: 1700000600,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n\nexport const missingFields: Flow.StepExample = {\n  public: false,\n  description:\n    'Graceful handling when ingest is missing: each empty input logs one warning, and the hash is still generated.',\n  in: {\n    name: 'session start',\n    data: { id: 's3ss10n' },\n    id: 'ev-1700000601',\n    trigger: 'load',\n    entity: 'session',\n    action: 'start',\n    timestamp: 1700000601,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'session start',\n          data: { id: 's3ss10n' },\n          user: { hash: 'e183220b699c10a8' },\n          id: 'ev-1700000601',\n          trigger: 'load',\n          entity: 'session',\n          action: 'start',\n          timestamp: 1700000601,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n\nexport const ipAnonymization: Flow.StepExample = {\n  title: 'IP anonymization',\n  description:\n    'The ip input anonymizes the IP before hashing (IPv4 /24, IPv6 /48), so visitors from the same 10.0.42.* subnet ' +\n    'with the same browser, major version and OS share a hash within a day. No custom fn needed. Config: { salt: \"$env.FINGERPRINT_SALT\", length: 16 }',\n  in: {\n    name: 'page view',\n    data: {\n      domain: 'www.example.com',\n      title: 'Privacy Policy',\n      id: '/privacy',\n    },\n    id: 'ev-1700000602',\n    trigger: 'load',\n    entity: 'page',\n    action: 'view',\n    timestamp: 1700000602,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'page view',\n          data: {\n            domain: 'www.example.com',\n            title: 'Privacy Policy',\n            id: '/privacy',\n          },\n          user: { hash: '44d9154b9a9b3792' },\n          id: 'ev-1700000602',\n          trigger: 'load',\n          entity: 'page',\n          action: 'view',\n          timestamp: 1700000602,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n","import type { Hint } from '@walkeros/core';\n\nexport const hints: Hint.Hints = {\n  'ingest-prerequisite': {\n    text: 'The default inputs ip and userAgent read ingest.ip and ingest.userAgent, so the server source must have config.ingest configured. config.ingest MUST use the map operator with direct request field paths (no req. prefix); a bare object like { ip: \"req.ip\" } is silently inert and leaves ingest empty. An input that resolves empty logs one warning (\"Fingerprint input ... resolved empty\") and the hash is still generated, but less distinct. Behind a load balancer the request ip is the balancer; read the client from headers.x-forwarded-for instead.',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            sources: {\n              express: {\n                package: '@walkeros/server-source-express',\n                next: 'fingerprint',\n                config: {\n                  settings: { port: 8080 },\n                  ingest: {\n                    map: {\n                      ip: { key: 'ip' },\n                      userAgent: { key: 'headers.user-agent' },\n                    },\n                  },\n                },\n              },\n            },\n            transformers: {\n              fingerprint: {\n                package: '@walkeros/server-transformer-fingerprint',\n                config: {\n                  settings: { salt: '$env.FINGERPRINT_SALT' },\n                },\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'salt-and-rotation': {\n    text: 'The salt keys the hash (HMAC), so it cannot be recomputed or reversed to the IP without it. Pass it via $env so it stays out of the flow file, and use one salt per deployment. Without a salt the transformer runs but logs a warning at startup. Rotation is built in (daily by default, UTC windows): do not add a date field for it. For another window, set rotate: \"none\" and add the window as a field. Setting fields switches the default inputs off, so name them too: { rotate: \"none\", ip: \"ingest.ip\", userAgent: \"ingest.userAgent\", site: \"event.source.url\", fields: [{ fn: () => new Date().toISOString().slice(0, 7) }] } rotates monthly. rotate: \"none\" without such a field keeps one hash per visitor indefinitely, which is a privacy decision, not a default.',\n  },\n  'site-sources': {\n    text: 'site defaults to the hostname of event.source.url, which the walkerOS browser and dataLayer sources set on every event and transformer-ga4 sets from the page URL of the hit (dl). Older transformer-ga4 versions did not set it, so upgrading transformer-ga4 changes the hash of GA4-decoded events once: site now joins the hash. Events without source.url (server-side events, GA4 hits without dl) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: \"headers.origin\" }), or a static { value: \"example.com\" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt.',\n  },\n  'extra-fields': {\n    text: 'fields adds values to the hash as they resolve from { event, ingest }, in order. When fields is set, the named inputs ip, userAgent and site are only used if set explicitly, so an existing fields config keeps its input set. To transform a value before hashing, use fn alone: it receives { event, ingest } and returns the value. A fn next to a key never runs. The IP never needs a custom fn: the ip input anonymizes it (IPv4 /24, IPv6 /48).',\n  },\n};\n"],"mappings":"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","names":["import_dev"]}

package/dist/dev.mjs

@@ -1 +1 @@
-var e=Object.defineProperty,t=(t,i)=>{for(var s in i)e(t,s,{get:i[s],enumerable:!0})},i={};t(i,{SettingsSchema:()=>o,settings:()=>d});import{zodToSchema as s}from"@walkeros/core/dev";import{z as n}from"@walkeros/core/dev";var a=n.union([n.string().describe('Dot-notation path: "ingest.ip", "event.data.userId"'),n.object({key:n.string().optional().describe("Source property path"),value:n.unknown().optional().describe("Static value or fallback"),fn:n.string().optional().describe("$code: function receiving { event, ingest } that returns the value. Runs only when no key is set.")}).describe("Mapping value config for computed fields")]),r=n.union([a,n.literal(!1).describe("Switch this input off")]),o=n.object({salt:n.string().optional().describe('Secret key for the hash (HMAC), e.g. "$env.FINGERPRINT_SALT". Without it the hash can be reversed to the IP; a warning is logged.'),rotate:n.enum(["daily","hourly","none"]).optional().describe('Rotation window in UTC: the same visitor gets a new hash each window. Default: "daily"'),ip:r.optional().describe('Client IP, anonymized to /24 (IPv4) or /48 (IPv6) before hashing. Default: "ingest.ip" when fields is not set'),userAgent:r.optional().describe('User agent, reduced to browser, major version and OS before hashing. Default: "ingest.userAgent" when fields is not set'),site:r.optional().describe('Site the visitor is on; a URL is reduced to its hostname. Default: "event.source.url" when fields is not set'),fields:n.array(a).optional().describe("Extra fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }. When set, named inputs are only used if set explicitly."),output:n.string().optional().describe('Dot-notation path where hash is stored on the event. Default: "user.hash"'),length:n.number().int().positive().optional().describe("Truncate hash to this length. Default: full 64-char SHA-256 hash")}).describe("Fingerprint transformer: a cookieless, privacy-friendly visitor hash"),d=s(o),l={};t(l,{step:()=>h});var h={};t(h,{ipAnonymization:()=>c,missingFields:()=>g,serverFingerprint:()=>p});var p={title:"Server fingerprint",description:'Default server fingerprint: the anonymized ingest.ip, the reduced ingest.userAgent and the site, keyed with settings.salt and rotated daily. Config: { salt: "$env.FINGERPRINT_SALT", length: 16 }. Requires source config.ingest. The hash depends on the salt and the day.',in:{name:"page view",data:{domain:"www.example.com",title:"Getting Started",id:"/docs/getting-started"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"page view",data:{domain:"www.example.com",title:"Getting Started",id:"/docs/getting-started"},user:{hash:"158f99cc06e33fd6"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}}}]]},g={public:!1,description:"Graceful handling when ingest is missing: each empty input logs one warning, and the hash is still generated.",in:{name:"session start",data:{id:"s3ss10n"},id:"ev-1700000601",trigger:"load",entity:"session",action:"start",timestamp:1700000601,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"session start",data:{id:"s3ss10n"},user:{hash:"e183220b699c10a8"},id:"ev-1700000601",trigger:"load",entity:"session",action:"start",timestamp:1700000601,source:{type:"express",platform:"server"}}}]]},c={title:"IP anonymization",description:'The ip input anonymizes the IP before hashing (IPv4 /24, IPv6 /48), so visitors from the same 10.0.42.* subnet with the same browser, major version and OS share a hash within a day. No custom fn needed. Config: { salt: "$env.FINGERPRINT_SALT", length: 16 }',in:{name:"page view",data:{domain:"www.example.com",title:"Privacy Policy",id:"/privacy"},id:"ev-1700000602",trigger:"load",entity:"page",action:"view",timestamp:1700000602,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"page view",data:{domain:"www.example.com",title:"Privacy Policy",id:"/privacy"},user:{hash:"44d9154b9a9b3792"},id:"ev-1700000602",trigger:"load",entity:"page",action:"view",timestamp:1700000602,source:{type:"express",platform:"server"}}}]]},u={"ingest-prerequisite":{text:'The default inputs ip and userAgent read ingest.ip and ingest.userAgent, so the server source must have config.ingest configured. config.ingest MUST use the map operator with direct request field paths (no req. prefix); a bare object like { ip: "req.ip" } is silently inert and leaves ingest empty. An input that resolves empty logs one warning ("Fingerprint input ... resolved empty") and the hash is still generated, but less distinct. Behind a load balancer the request ip is the balancer; read the client from headers.x-forwarded-for instead.',code:[{lang:"json",code:JSON.stringify({sources:{express:{package:"@walkeros/server-source-express",next:"fingerprint",config:{settings:{port:8080},ingest:{map:{ip:{key:"ip"},userAgent:{key:"headers.user-agent"}}}}}},transformers:{fingerprint:{package:"@walkeros/server-transformer-fingerprint",config:{settings:{salt:"$env.FINGERPRINT_SALT"}}}}},null,2)}]},"salt-and-rotation":{text:'The salt keys the hash (HMAC), so it cannot be recomputed or reversed to the IP without it. Pass it via $env so it stays out of the flow file, and use one salt per deployment. Without a salt the transformer runs but logs a warning at startup. Rotation is built in (daily by default, UTC windows): do not add a date field for it. For another window, set rotate: "none" and add the window as a field. Setting fields switches the default inputs off, so name them too: { rotate: "none", ip: "ingest.ip", userAgent: "ingest.userAgent", site: "event.source.url", fields: [{ fn: () => new Date().toISOString().slice(0, 7) }] } rotates monthly. rotate: "none" without such a field keeps one hash per visitor indefinitely, which is a privacy decision, not a default.'},"site-sources":{text:'site defaults to the hostname of event.source.url, which the walkerOS browser source sets on every event. Events without it (GA4 hits decoded by transformer-ga4, server-side events) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: "headers.origin" }), or a static { value: "example.com" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt.'},"extra-fields":{text:"fields adds values to the hash as they resolve from { event, ingest }, in order. When fields is set, the named inputs ip, userAgent and site are only used if set explicitly, so an existing fields config keeps its input set. To transform a value before hashing, use fn alone: it receives { event, ingest } and returns the value. A fn next to a key never runs. The IP never needs a custom fn: the ip input anonymizes it (IPv4 /24, IPv6 /48)."}};export{l as examples,u as hints,i as schemas};//# sourceMappingURL=dev.mjs.map
+var e=Object.defineProperty,t=(t,s)=>{for(var i in s)e(t,i,{get:s[i],enumerable:!0})},s={};t(s,{SettingsSchema:()=>d,settings:()=>h});import{zodToSchema as i}from"@walkeros/core/dev";import{schemas as n,z as a}from"@walkeros/core/dev";var r=n.MappingSchemas.ValueSchema,o=a.union([r,a.literal(!1).describe("Switch this input off")]),d=a.object({salt:a.string().optional().describe('Secret key for the hash (HMAC), e.g. "$env.FINGERPRINT_SALT". Without it the hash can be reversed to the IP; a warning is logged.'),rotate:a.enum(["daily","hourly","none"]).optional().describe('Rotation window in UTC: the same visitor gets a new hash each window. Default: "daily"'),ip:o.optional().describe('Client IP, anonymized to /24 (IPv4) or /48 (IPv6) before hashing. Default: "ingest.ip" when fields is not set'),userAgent:o.optional().describe('User agent, reduced to browser, major version and OS before hashing. Default: "ingest.userAgent" when fields is not set'),site:o.optional().describe('Site the visitor is on; a URL is reduced to its hostname. Default: "event.source.url" when fields is not set'),fields:a.array(r).optional().describe("Extra fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }. When set, named inputs are only used if set explicitly."),output:a.string().optional().describe('Dot-notation path where hash is stored on the event. Default: "user.hash"'),length:a.number().int().positive().optional().describe("Truncate hash to this length. Default: full 64-char SHA-256 hash")}).describe("Fingerprint transformer: a cookieless, privacy-friendly visitor hash"),h=i(d),l={};t(l,{step:()=>p});var p={};t(p,{ipAnonymization:()=>c,missingFields:()=>u,serverFingerprint:()=>g});var g={title:"Server fingerprint",description:'Default server fingerprint: the anonymized ingest.ip, the reduced ingest.userAgent and the site, keyed with settings.salt and rotated daily. Config: { salt: "$env.FINGERPRINT_SALT", length: 16 }. Requires source config.ingest. The hash depends on the salt and the day.',in:{name:"page view",data:{domain:"www.example.com",title:"Getting Started",id:"/docs/getting-started"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"page view",data:{domain:"www.example.com",title:"Getting Started",id:"/docs/getting-started"},user:{hash:"158f99cc06e33fd6"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}}}]]},u={public:!1,description:"Graceful handling when ingest is missing: each empty input logs one warning, and the hash is still generated.",in:{name:"session start",data:{id:"s3ss10n"},id:"ev-1700000601",trigger:"load",entity:"session",action:"start",timestamp:1700000601,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"session start",data:{id:"s3ss10n"},user:{hash:"e183220b699c10a8"},id:"ev-1700000601",trigger:"load",entity:"session",action:"start",timestamp:1700000601,source:{type:"express",platform:"server"}}}]]},c={title:"IP anonymization",description:'The ip input anonymizes the IP before hashing (IPv4 /24, IPv6 /48), so visitors from the same 10.0.42.* subnet with the same browser, major version and OS share a hash within a day. No custom fn needed. Config: { salt: "$env.FINGERPRINT_SALT", length: 16 }',in:{name:"page view",data:{domain:"www.example.com",title:"Privacy Policy",id:"/privacy"},id:"ev-1700000602",trigger:"load",entity:"page",action:"view",timestamp:1700000602,source:{type:"express",platform:"server"}},out:[["return",{event:{name:"page view",data:{domain:"www.example.com",title:"Privacy Policy",id:"/privacy"},user:{hash:"44d9154b9a9b3792"},id:"ev-1700000602",trigger:"load",entity:"page",action:"view",timestamp:1700000602,source:{type:"express",platform:"server"}}}]]},f={"ingest-prerequisite":{text:'The default inputs ip and userAgent read ingest.ip and ingest.userAgent, so the server source must have config.ingest configured. config.ingest MUST use the map operator with direct request field paths (no req. prefix); a bare object like { ip: "req.ip" } is silently inert and leaves ingest empty. An input that resolves empty logs one warning ("Fingerprint input ... resolved empty") and the hash is still generated, but less distinct. Behind a load balancer the request ip is the balancer; read the client from headers.x-forwarded-for instead.',code:[{lang:"json",code:JSON.stringify({sources:{express:{package:"@walkeros/server-source-express",next:"fingerprint",config:{settings:{port:8080},ingest:{map:{ip:{key:"ip"},userAgent:{key:"headers.user-agent"}}}}}},transformers:{fingerprint:{package:"@walkeros/server-transformer-fingerprint",config:{settings:{salt:"$env.FINGERPRINT_SALT"}}}}},null,2)}]},"salt-and-rotation":{text:'The salt keys the hash (HMAC), so it cannot be recomputed or reversed to the IP without it. Pass it via $env so it stays out of the flow file, and use one salt per deployment. Without a salt the transformer runs but logs a warning at startup. Rotation is built in (daily by default, UTC windows): do not add a date field for it. For another window, set rotate: "none" and add the window as a field. Setting fields switches the default inputs off, so name them too: { rotate: "none", ip: "ingest.ip", userAgent: "ingest.userAgent", site: "event.source.url", fields: [{ fn: () => new Date().toISOString().slice(0, 7) }] } rotates monthly. rotate: "none" without such a field keeps one hash per visitor indefinitely, which is a privacy decision, not a default.'},"site-sources":{text:'site defaults to the hostname of event.source.url, which the walkerOS browser and dataLayer sources set on every event and transformer-ga4 sets from the page URL of the hit (dl). Older transformer-ga4 versions did not set it, so upgrading transformer-ga4 changes the hash of GA4-decoded events once: site now joins the hash. Events without source.url (server-side events, GA4 hits without dl) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: "headers.origin" }), or a static { value: "example.com" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt.'},"extra-fields":{text:"fields adds values to the hash as they resolve from { event, ingest }, in order. When fields is set, the named inputs ip, userAgent and site are only used if set explicitly, so an existing fields config keeps its input set. To transform a value before hashing, use fn alone: it receives { event, ingest } and returns the value. A fn next to a key never runs. The IP never needs a custom fn: the ip input anonymizes it (IPv4 /24, IPv6 /48)."}};export{l as examples,f as hints,s as schemas};//# sourceMappingURL=dev.mjs.map

package/dist/dev.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/schemas/index.ts","../src/schemas/settings.ts","../src/examples/index.ts","../src/examples/step.ts","../src/hints.ts"],"sourcesContent":["import { zodToSchema } from '@walkeros/core/dev';\nimport { SettingsSchema } from './settings';\n\nexport { SettingsSchema, type Settings } from './settings';\nexport const settings = zodToSchema(SettingsSchema);\n","import { z } from '@walkeros/core/dev';\n\nconst FieldSchema = z.union([\n  z.string().describe('Dot-notation path: \"ingest.ip\", \"event.data.userId\"'),\n  z\n    .object({\n      key: z.string().optional().describe('Source property path'),\n      value: z.unknown().optional().describe('Static value or fallback'),\n      fn: z\n        .string()\n        .optional()\n        .describe(\n          '$code: function receiving { event, ingest } that returns the value. Runs only when no key is set.',\n        ),\n    })\n    .describe('Mapping value config for computed fields'),\n]);\n\nconst InputSchema = z.union([\n  FieldSchema,\n  z.literal(false).describe('Switch this input off'),\n]);\n\n/**\n * Fingerprint transformer settings schema.\n *\n * Mirrors: types.ts FingerprintSettings\n */\nexport const SettingsSchema = z\n  .object({\n    salt: z\n      .string()\n      .optional()\n      .describe(\n        'Secret key for the hash (HMAC), e.g. \"$env.FINGERPRINT_SALT\". Without it the hash can be reversed to the IP; a warning is logged.',\n      ),\n    rotate: z\n      .enum(['daily', 'hourly', 'none'])\n      .optional()\n      .describe(\n        'Rotation window in UTC: the same visitor gets a new hash each window. Default: \"daily\"',\n      ),\n    ip: InputSchema.optional().describe(\n      'Client IP, anonymized to /24 (IPv4) or /48 (IPv6) before hashing. Default: \"ingest.ip\" when fields is not set',\n    ),\n    userAgent: InputSchema.optional().describe(\n      'User agent, reduced to browser, major version and OS before hashing. Default: \"ingest.userAgent\" when fields is not set',\n    ),\n    site: InputSchema.optional().describe(\n      'Site the visitor is on; a URL is reduced to its hostname. Default: \"event.source.url\" when fields is not set',\n    ),\n    fields: z\n      .array(FieldSchema)\n      .optional()\n      .describe(\n        'Extra fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }. When set, named inputs are only used if set explicitly.',\n      ),\n    output: z\n      .string()\n      .optional()\n      .describe(\n        'Dot-notation path where hash is stored on the event. Default: \"user.hash\"',\n      ),\n    length: z\n      .number()\n      .int()\n      .positive()\n      .optional()\n      .describe(\n        'Truncate hash to this length. Default: full 64-char SHA-256 hash',\n      ),\n  })\n  .describe(\n    'Fingerprint transformer: a cookieless, privacy-friendly visitor hash',\n  );\n\nexport type Settings = z.infer<typeof SettingsSchema>;\n","export * as step from './step';\n","import type { Flow } from '@walkeros/core';\n\nexport const serverFingerprint: Flow.StepExample = {\n  title: 'Server fingerprint',\n  description:\n    'Default server fingerprint: the anonymized ingest.ip, the reduced ingest.userAgent and the site, keyed with settings.salt and rotated daily. ' +\n    'Config: { salt: \"$env.FINGERPRINT_SALT\", length: 16 }. Requires source config.ingest. The hash depends on the salt and the day.',\n  in: {\n    name: 'page view',\n    data: {\n      domain: 'www.example.com',\n      title: 'Getting Started',\n      id: '/docs/getting-started',\n    },\n    id: 'ev-1700000600',\n    trigger: 'load',\n    entity: 'page',\n    action: 'view',\n    timestamp: 1700000600,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'page view',\n          data: {\n            domain: 'www.example.com',\n            title: 'Getting Started',\n            id: '/docs/getting-started',\n          },\n          user: { hash: '158f99cc06e33fd6' },\n          id: 'ev-1700000600',\n          trigger: 'load',\n          entity: 'page',\n          action: 'view',\n          timestamp: 1700000600,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n\nexport const missingFields: Flow.StepExample = {\n  public: false,\n  description:\n    'Graceful handling when ingest is missing: each empty input logs one warning, and the hash is still generated.',\n  in: {\n    name: 'session start',\n    data: { id: 's3ss10n' },\n    id: 'ev-1700000601',\n    trigger: 'load',\n    entity: 'session',\n    action: 'start',\n    timestamp: 1700000601,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'session start',\n          data: { id: 's3ss10n' },\n          user: { hash: 'e183220b699c10a8' },\n          id: 'ev-1700000601',\n          trigger: 'load',\n          entity: 'session',\n          action: 'start',\n          timestamp: 1700000601,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n\nexport const ipAnonymization: Flow.StepExample = {\n  title: 'IP anonymization',\n  description:\n    'The ip input anonymizes the IP before hashing (IPv4 /24, IPv6 /48), so visitors from the same 10.0.42.* subnet ' +\n    'with the same browser, major version and OS share a hash within a day. No custom fn needed. Config: { salt: \"$env.FINGERPRINT_SALT\", length: 16 }',\n  in: {\n    name: 'page view',\n    data: {\n      domain: 'www.example.com',\n      title: 'Privacy Policy',\n      id: '/privacy',\n    },\n    id: 'ev-1700000602',\n    trigger: 'load',\n    entity: 'page',\n    action: 'view',\n    timestamp: 1700000602,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'page view',\n          data: {\n            domain: 'www.example.com',\n            title: 'Privacy Policy',\n            id: '/privacy',\n          },\n          user: { hash: '44d9154b9a9b3792' },\n          id: 'ev-1700000602',\n          trigger: 'load',\n          entity: 'page',\n          action: 'view',\n          timestamp: 1700000602,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n","import type { Hint } from '@walkeros/core';\n\nexport const hints: Hint.Hints = {\n  'ingest-prerequisite': {\n    text: 'The default inputs ip and userAgent read ingest.ip and ingest.userAgent, so the server source must have config.ingest configured. config.ingest MUST use the map operator with direct request field paths (no req. prefix); a bare object like { ip: \"req.ip\" } is silently inert and leaves ingest empty. An input that resolves empty logs one warning (\"Fingerprint input ... resolved empty\") and the hash is still generated, but less distinct. Behind a load balancer the request ip is the balancer; read the client from headers.x-forwarded-for instead.',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            sources: {\n              express: {\n                package: '@walkeros/server-source-express',\n                next: 'fingerprint',\n                config: {\n                  settings: { port: 8080 },\n                  ingest: {\n                    map: {\n                      ip: { key: 'ip' },\n                      userAgent: { key: 'headers.user-agent' },\n                    },\n                  },\n                },\n              },\n            },\n            transformers: {\n              fingerprint: {\n                package: '@walkeros/server-transformer-fingerprint',\n                config: {\n                  settings: { salt: '$env.FINGERPRINT_SALT' },\n                },\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'salt-and-rotation': {\n    text: 'The salt keys the hash (HMAC), so it cannot be recomputed or reversed to the IP without it. Pass it via $env so it stays out of the flow file, and use one salt per deployment. Without a salt the transformer runs but logs a warning at startup. Rotation is built in (daily by default, UTC windows): do not add a date field for it. For another window, set rotate: \"none\" and add the window as a field. Setting fields switches the default inputs off, so name them too: { rotate: \"none\", ip: \"ingest.ip\", userAgent: \"ingest.userAgent\", site: \"event.source.url\", fields: [{ fn: () => new Date().toISOString().slice(0, 7) }] } rotates monthly. rotate: \"none\" without such a field keeps one hash per visitor indefinitely, which is a privacy decision, not a default.',\n  },\n  'site-sources': {\n    text: 'site defaults to the hostname of event.source.url, which the walkerOS browser source sets on every event. Events without it (GA4 hits decoded by transformer-ga4, server-side events) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: \"headers.origin\" }), or a static { value: \"example.com\" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt.',\n  },\n  'extra-fields': {\n    text: 'fields adds values to the hash as they resolve from { event, ingest }, in order. When fields is set, the named inputs ip, userAgent and site are only used if set explicitly, so an existing fields config keeps its input set. To transform a value before hashing, use fn alone: it receives { event, ingest } and returns the value. A fn next to a key never runs. The IP never needs a custom fn: the ip input anonymizes it (IPv4 /24, IPv6 /48).',\n  },\n};\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/schemas/index.ts","../src/schemas/settings.ts","../src/examples/index.ts","../src/examples/step.ts","../src/hints.ts"],"sourcesContent":["import { zodToSchema } from '@walkeros/core/dev';\nimport { SettingsSchema } from './settings';\n\nexport { SettingsSchema, type Settings } from './settings';\nexport const settings = zodToSchema(SettingsSchema);\n","import { schemas, z } from '@walkeros/core/dev';\n\n// A field or input is a Mapping.Value (a path, a constant, a value config\n// or a fallback list), resolved via getMappingValue with { event, ingest }.\nconst FieldSchema = schemas.MappingSchemas.ValueSchema;\n\nconst InputSchema = z.union([\n  FieldSchema,\n  z.literal(false).describe('Switch this input off'),\n]);\n\n/**\n * Fingerprint transformer settings schema.\n *\n * Mirrors: types.ts FingerprintSettings\n */\nexport const SettingsSchema = z\n  .object({\n    salt: z\n      .string()\n      .optional()\n      .describe(\n        'Secret key for the hash (HMAC), e.g. \"$env.FINGERPRINT_SALT\". Without it the hash can be reversed to the IP; a warning is logged.',\n      ),\n    rotate: z\n      .enum(['daily', 'hourly', 'none'])\n      .optional()\n      .describe(\n        'Rotation window in UTC: the same visitor gets a new hash each window. Default: \"daily\"',\n      ),\n    ip: InputSchema.optional().describe(\n      'Client IP, anonymized to /24 (IPv4) or /48 (IPv6) before hashing. Default: \"ingest.ip\" when fields is not set',\n    ),\n    userAgent: InputSchema.optional().describe(\n      'User agent, reduced to browser, major version and OS before hashing. Default: \"ingest.userAgent\" when fields is not set',\n    ),\n    site: InputSchema.optional().describe(\n      'Site the visitor is on; a URL is reduced to its hostname. Default: \"event.source.url\" when fields is not set',\n    ),\n    fields: z\n      .array(FieldSchema)\n      .optional()\n      .describe(\n        'Extra fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }. When set, named inputs are only used if set explicitly.',\n      ),\n    output: z\n      .string()\n      .optional()\n      .describe(\n        'Dot-notation path where hash is stored on the event. Default: \"user.hash\"',\n      ),\n    length: z\n      .number()\n      .int()\n      .positive()\n      .optional()\n      .describe(\n        'Truncate hash to this length. Default: full 64-char SHA-256 hash',\n      ),\n  })\n  .describe(\n    'Fingerprint transformer: a cookieless, privacy-friendly visitor hash',\n  );\n\nexport type Settings = z.infer<typeof SettingsSchema>;\n","export * as step from './step';\n","import type { Flow } from '@walkeros/core';\n\nexport const serverFingerprint: Flow.StepExample = {\n  title: 'Server fingerprint',\n  description:\n    'Default server fingerprint: the anonymized ingest.ip, the reduced ingest.userAgent and the site, keyed with settings.salt and rotated daily. ' +\n    'Config: { salt: \"$env.FINGERPRINT_SALT\", length: 16 }. Requires source config.ingest. The hash depends on the salt and the day.',\n  in: {\n    name: 'page view',\n    data: {\n      domain: 'www.example.com',\n      title: 'Getting Started',\n      id: '/docs/getting-started',\n    },\n    id: 'ev-1700000600',\n    trigger: 'load',\n    entity: 'page',\n    action: 'view',\n    timestamp: 1700000600,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'page view',\n          data: {\n            domain: 'www.example.com',\n            title: 'Getting Started',\n            id: '/docs/getting-started',\n          },\n          user: { hash: '158f99cc06e33fd6' },\n          id: 'ev-1700000600',\n          trigger: 'load',\n          entity: 'page',\n          action: 'view',\n          timestamp: 1700000600,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n\nexport const missingFields: Flow.StepExample = {\n  public: false,\n  description:\n    'Graceful handling when ingest is missing: each empty input logs one warning, and the hash is still generated.',\n  in: {\n    name: 'session start',\n    data: { id: 's3ss10n' },\n    id: 'ev-1700000601',\n    trigger: 'load',\n    entity: 'session',\n    action: 'start',\n    timestamp: 1700000601,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'session start',\n          data: { id: 's3ss10n' },\n          user: { hash: 'e183220b699c10a8' },\n          id: 'ev-1700000601',\n          trigger: 'load',\n          entity: 'session',\n          action: 'start',\n          timestamp: 1700000601,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n\nexport const ipAnonymization: Flow.StepExample = {\n  title: 'IP anonymization',\n  description:\n    'The ip input anonymizes the IP before hashing (IPv4 /24, IPv6 /48), so visitors from the same 10.0.42.* subnet ' +\n    'with the same browser, major version and OS share a hash within a day. No custom fn needed. Config: { salt: \"$env.FINGERPRINT_SALT\", length: 16 }',\n  in: {\n    name: 'page view',\n    data: {\n      domain: 'www.example.com',\n      title: 'Privacy Policy',\n      id: '/privacy',\n    },\n    id: 'ev-1700000602',\n    trigger: 'load',\n    entity: 'page',\n    action: 'view',\n    timestamp: 1700000602,\n    source: { type: 'express', platform: 'server' },\n  },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          name: 'page view',\n          data: {\n            domain: 'www.example.com',\n            title: 'Privacy Policy',\n            id: '/privacy',\n          },\n          user: { hash: '44d9154b9a9b3792' },\n          id: 'ev-1700000602',\n          trigger: 'load',\n          entity: 'page',\n          action: 'view',\n          timestamp: 1700000602,\n          source: { type: 'express', platform: 'server' },\n        },\n      },\n    ],\n  ],\n};\n","import type { Hint } from '@walkeros/core';\n\nexport const hints: Hint.Hints = {\n  'ingest-prerequisite': {\n    text: 'The default inputs ip and userAgent read ingest.ip and ingest.userAgent, so the server source must have config.ingest configured. config.ingest MUST use the map operator with direct request field paths (no req. prefix); a bare object like { ip: \"req.ip\" } is silently inert and leaves ingest empty. An input that resolves empty logs one warning (\"Fingerprint input ... resolved empty\") and the hash is still generated, but less distinct. Behind a load balancer the request ip is the balancer; read the client from headers.x-forwarded-for instead.',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            sources: {\n              express: {\n                package: '@walkeros/server-source-express',\n                next: 'fingerprint',\n                config: {\n                  settings: { port: 8080 },\n                  ingest: {\n                    map: {\n                      ip: { key: 'ip' },\n                      userAgent: { key: 'headers.user-agent' },\n                    },\n                  },\n                },\n              },\n            },\n            transformers: {\n              fingerprint: {\n                package: '@walkeros/server-transformer-fingerprint',\n                config: {\n                  settings: { salt: '$env.FINGERPRINT_SALT' },\n                },\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'salt-and-rotation': {\n    text: 'The salt keys the hash (HMAC), so it cannot be recomputed or reversed to the IP without it. Pass it via $env so it stays out of the flow file, and use one salt per deployment. Without a salt the transformer runs but logs a warning at startup. Rotation is built in (daily by default, UTC windows): do not add a date field for it. For another window, set rotate: \"none\" and add the window as a field. Setting fields switches the default inputs off, so name them too: { rotate: \"none\", ip: \"ingest.ip\", userAgent: \"ingest.userAgent\", site: \"event.source.url\", fields: [{ fn: () => new Date().toISOString().slice(0, 7) }] } rotates monthly. rotate: \"none\" without such a field keeps one hash per visitor indefinitely, which is a privacy decision, not a default.',\n  },\n  'site-sources': {\n    text: 'site defaults to the hostname of event.source.url, which the walkerOS browser and dataLayer sources set on every event and transformer-ga4 sets from the page URL of the hit (dl). Older transformer-ga4 versions did not set it, so upgrading transformer-ga4 changes the hash of GA4-decoded events once: site now joins the hash. Events without source.url (server-side events, GA4 hits without dl) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: \"headers.origin\" }), or a static { value: \"example.com\" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt.',\n  },\n  'extra-fields': {\n    text: 'fields adds values to the hash as they resolve from { event, ingest }, in order. When fields is set, the named inputs ip, userAgent and site are only used if set explicitly, so an existing fields config keeps its input set. To transform a value before hashing, use fn alone: it receives { event, ingest } and returns the value. A fn next to a key never runs. The IP never needs a custom fn: the ip input anonymizes it (IPv4 /24, IPv6 /48).',\n  },\n};\n"],"mappings":"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","names":[]}

package/dist/walkerOS.json

@@ -1,11 +1,12 @@
 {
   "$meta": {
     "package": "@walkeros/server-transformer-fingerprint",
-    "version": "4.7.0-next-1790245733116",
+    "version": "4.7.0",
     "type": "transformer",
     "platform": [
       "server"
     ],
+    "exports": {},
     "docs": "https://www.walkeros.io/docs/transformers/fingerprint",
     "source": "https://github.com/elbwalker/walkerOS/tree/main/packages/server/transformers/fingerprint/src"
   },
@@ -31,30 +32,7 @@
           "description": "Client IP, anonymized to /24 (IPv4) or /48 (IPv6) before hashing. Default: \"ingest.ip\" when fields is not set",
           "anyOf": [
             {
-              "anyOf": [
-                {
-                  "type": "string",
-                  "description": "Dot-notation path: \"ingest.ip\", \"event.data.userId\""
-                },
-                {
-                  "type": "object",
-                  "properties": {
-                    "key": {
-                      "description": "Source property path",
-                      "type": "string"
-                    },
-                    "value": {
-                      "description": "Static value or fallback"
-                    },
-                    "fn": {
-                      "description": "$code: function receiving { event, ingest } that returns the value. Runs only when no key is set.",
-                      "type": "string"
-                    }
-                  },
-                  "additionalProperties": false,
-                  "description": "Mapping value config for computed fields"
-                }
-              ]
+              "$ref": "#/definitions/MappingValue"
             },
             {
               "type": "boolean",
@@ -67,30 +45,7 @@
           "description": "User agent, reduced to browser, major version and OS before hashing. Default: \"ingest.userAgent\" when fields is not set",
           "anyOf": [
             {
-              "anyOf": [
-                {
-                  "type": "string",
-                  "description": "Dot-notation path: \"ingest.ip\", \"event.data.userId\""
-                },
-                {
-                  "type": "object",
-                  "properties": {
-                    "key": {
-                      "description": "Source property path",
-                      "type": "string"
-                    },
-                    "value": {
-                      "description": "Static value or fallback"
-                    },
-                    "fn": {
-                      "description": "$code: function receiving { event, ingest } that returns the value. Runs only when no key is set.",
-                      "type": "string"
-                    }
-                  },
-                  "additionalProperties": false,
-                  "description": "Mapping value config for computed fields"
-                }
-              ]
+              "$ref": "#/definitions/MappingValue"
             },
             {
               "type": "boolean",
@@ -103,30 +58,7 @@
           "description": "Site the visitor is on; a URL is reduced to its hostname. Default: \"event.source.url\" when fields is not set",
           "anyOf": [
             {
-              "anyOf": [
-                {
-                  "type": "string",
-                  "description": "Dot-notation path: \"ingest.ip\", \"event.data.userId\""
-                },
-                {
-                  "type": "object",
-                  "properties": {
-                    "key": {
-                      "description": "Source property path",
-                      "type": "string"
-                    },
-                    "value": {
-                      "description": "Static value or fallback"
-                    },
-                    "fn": {
-                      "description": "$code: function receiving { event, ingest } that returns the value. Runs only when no key is set.",
-                      "type": "string"
-                    }
-                  },
-                  "additionalProperties": false,
-                  "description": "Mapping value config for computed fields"
-                }
-              ]
+              "$ref": "#/definitions/MappingValue"
             },
             {
               "type": "boolean",
@@ -139,30 +71,7 @@
           "description": "Extra fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }. When set, named inputs are only used if set explicitly.",
           "type": "array",
           "items": {
-            "anyOf": [
-              {
-                "type": "string",
-                "description": "Dot-notation path: \"ingest.ip\", \"event.data.userId\""
-              },
-              {
-                "type": "object",
-                "properties": {
-                  "key": {
-                    "description": "Source property path",
-                    "type": "string"
-                  },
-                  "value": {
-                    "description": "Static value or fallback"
-                  },
-                  "fn": {
-                    "description": "$code: function receiving { event, ingest } that returns the value. Runs only when no key is set.",
-                    "type": "string"
-                  }
-                },
-                "additionalProperties": false,
-                "description": "Mapping value config for computed fields"
-              }
-            ]
+            "$ref": "#/definitions/MappingValue"
           }
         },
         "output": {
@@ -177,7 +86,157 @@
         }
       },
       "additionalProperties": false,
-      "description": "Fingerprint transformer: a cookieless, privacy-friendly visitor hash"
+      "description": "Fingerprint transformer: a cookieless, privacy-friendly visitor hash",
+      "definitions": {
+        "MappingValue": {
+          "title": "Mapping.Value",
+          "description": "Polymorphic transform primitive used in every mapping field. A string path, constant, operator object (map/loop/set/condition/consent), or array of values.",
+          "anyOf": [
+            {
+              "type": "string",
+              "description": "String value or property path (e.g., \"data.id\")"
+            },
+            {
+              "type": "number",
+              "description": "Numeric value"
+            },
+            {
+              "type": "boolean",
+              "description": "Boolean value"
+            },
+            {
+              "description": "Value transformation configuration with multiple strategies",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/MappingValueConfig"
+                }
+              ]
+            },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/MappingValue"
+              },
+              "description": "Array of values"
+            }
+          ]
+        },
+        "MappingMap": {
+          "title": "Mapping.Map",
+          "description": "Map: object mapping keys to transformation values.",
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "$ref": "#/definitions/MappingValue"
+          }
+        },
+        "MappingLoop": {
+          "title": "Mapping.Loop",
+          "description": "Loop tuple [source, transform] for iterating and transforming arrays.",
+          "minItems": 2,
+          "maxItems": 2,
+          "type": "array",
+          "items": [
+            {
+              "$ref": "#/definitions/MappingValue"
+            },
+            {
+              "$ref": "#/definitions/MappingValue"
+            }
+          ]
+        },
+        "MappingSet": {
+          "title": "Mapping.Set",
+          "description": "Set: array of values for selection or combination.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/MappingValue"
+          }
+        },
+        "WalkerOSConsent": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "boolean"
+          },
+          "title": "WalkerOS.Consent",
+          "description": "Consent state mapping. Keys are consent groups (e.g. marketing, functional), values are booleans for granted/denied."
+        },
+        "MappingValueConfig": {
+          "type": "object",
+          "properties": {
+            "key": {
+              "description": "Property path to extract from event (e.g., \"data.id\", \"user.email\")",
+              "type": "string"
+            },
+            "value": {
+              "description": "Static primitive value",
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "boolean"
+                }
+              ]
+            },
+            "fn": {
+              "description": "Custom transformation function as string (serialized)",
+              "type": "string"
+            },
+            "map": {
+              "description": "Object mapping: transform event data to structured output",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/MappingMap"
+                }
+              ]
+            },
+            "loop": {
+              "description": "Loop transformation: [source, transform] for array processing",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/MappingLoop"
+                }
+              ]
+            },
+            "set": {
+              "description": "Set of values: combine or select from multiple values",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/MappingSet"
+                }
+              ]
+            },
+            "consent": {
+              "description": "Required consent states to include this value",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/WalkerOSConsent"
+                }
+              ]
+            },
+            "condition": {
+              "description": "Condition function as string: return true to include value",
+              "type": "string"
+            },
+            "validate": {
+              "description": "Validation function as string: return true if value is valid",
+              "type": "string"
+            }
+          },
+          "additionalProperties": false,
+          "title": "Mapping.ValueConfig",
+          "description": "Object-form value transformation with map/loop/set/condition/consent etc."
+        }
+      }
     }
   },
   "examples": {
@@ -338,7 +397,7 @@
       "text": "The salt keys the hash (HMAC), so it cannot be recomputed or reversed to the IP without it. Pass it via $env so it stays out of the flow file, and use one salt per deployment. Without a salt the transformer runs but logs a warning at startup. Rotation is built in (daily by default, UTC windows): do not add a date field for it. For another window, set rotate: \"none\" and add the window as a field. Setting fields switches the default inputs off, so name them too: { rotate: \"none\", ip: \"ingest.ip\", userAgent: \"ingest.userAgent\", site: \"event.source.url\", fields: [{ fn: () => new Date().toISOString().slice(0, 7) }] } rotates monthly. rotate: \"none\" without such a field keeps one hash per visitor indefinitely, which is a privacy decision, not a default."
     },
     "site-sources": {
-      "text": "site defaults to the hostname of event.source.url, which the walkerOS browser source sets on every event. Events without it (GA4 hits decoded by transformer-ga4, server-side events) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: \"headers.origin\" }), or a static { value: \"example.com\" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt."
+      "text": "site defaults to the hostname of event.source.url, which the walkerOS browser and dataLayer sources set on every event and transformer-ga4 sets from the page URL of the hit (dl). Older transformer-ga4 versions did not set it, so upgrading transformer-ga4 changes the hash of GA4-decoded events once: site now joins the hash. Events without source.url (server-side events, GA4 hits without dl) need site pointed elsewhere: an ingest path such as ingest.property (a path parameter) or ingest.origin (map it in config.ingest first, e.g. origin: { key: \"headers.origin\" }), or a static { value: \"example.com\" }. site keeps one visitor apart across sites when one collector with one salt serves several of them; a single-site deployment with its own salt is already separated by the salt."
     },
     "extra-fields": {
       "text": "fields adds values to the hash as they resolve from { event, ingest }, in order. When fields is set, the named inputs ip, userAgent and site are only used if set explicitly, so an existing fields config keeps its input set. To transform a value before hashing, use fn alone: it receives { event, ingest } and returns the value. A fn next to a key never runs. The IP never needs a custom fn: the ip input anonymizes it (IPv4 /24, IPv6 /48)."

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@walkeros/server-transformer-fingerprint",
   "description": "Fingerprint transformer for walkerOS server - hash configurable fields for session continuity",
-  "version": "4.7.0-next-1790245733116",
+  "version": "4.7.0",
   "license": "MIT",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -27,8 +27,8 @@
     "update": "npx npm-check-updates -u && npm update"
   },
   "devDependencies": {
-    "@walkeros/core": "4.7.0-next-1790245733116",
-    "@walkeros/server-core": "4.7.0-next-1790245733116"
+    "@walkeros/core": "4.7.0",
+    "@walkeros/server-core": "4.7.0"
   },
   "repository": {
     "url": "git+https://github.com/elbwalker/walkerOS.git",
@@ -60,7 +60,7 @@
     }
   ],
   "dependencies": {
-    "@walkeros/core": "4.7.0-next-1790245733116",
-    "@walkeros/server-core": "4.7.0-next-1790245733116"
+    "@walkeros/core": "4.7.0",
+    "@walkeros/server-core": "4.7.0"
   }
 }