@walkeros/server-transformer-fingerprint 4.0.0 → 4.0.1-next-1778183328892

package/dist/dev.d.mts

@@ -0,0 +1,48 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Flow, Hint } from '@walkeros/core';
+
+/**
+ * Fingerprint transformer settings schema.
+ *
+ * Mirrors: types.ts FingerprintSettings
+ */
+declare const SettingsSchema: z.ZodObject<{
+    fields: 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>]>>;
+    output: z.ZodOptional<z.ZodString>;
+    length: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+
+type index$1_Settings = Settings;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, index$1_settings as settings };
+}
+
+declare const serverFingerprint: Flow.StepExample;
+declare const missingFields: Flow.StepExample;
+declare const ipAnonymization: Flow.StepExample;
+
+declare const step_ipAnonymization: typeof ipAnonymization;
+declare const step_missingFields: typeof missingFields;
+declare const step_serverFingerprint: typeof serverFingerprint;
+declare namespace step {
+  export { step_ipAnonymization as ipAnonymization, step_missingFields as missingFields, step_serverFingerprint as serverFingerprint };
+}
+
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_step as step };
+}
+
+declare const hints: Hint.Hints;
+
+export { index as examples, hints, index$1 as schemas };

package/dist/dev.d.ts

@@ -0,0 +1,48 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Flow, Hint } from '@walkeros/core';
+
+/**
+ * Fingerprint transformer settings schema.
+ *
+ * Mirrors: types.ts FingerprintSettings
+ */
+declare const SettingsSchema: z.ZodObject<{
+    fields: 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>]>>;
+    output: z.ZodOptional<z.ZodString>;
+    length: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+
+type index$1_Settings = Settings;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, index$1_settings as settings };
+}
+
+declare const serverFingerprint: Flow.StepExample;
+declare const missingFields: Flow.StepExample;
+declare const ipAnonymization: Flow.StepExample;
+
+declare const step_ipAnonymization: typeof ipAnonymization;
+declare const step_missingFields: typeof missingFields;
+declare const step_serverFingerprint: typeof serverFingerprint;
+declare namespace step {
+  export { step_ipAnonymization as ipAnonymization, step_missingFields as missingFields, step_serverFingerprint as serverFingerprint };
+}
+
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_step as step };
+}
+
+declare const hints: Hint.Hints;
+
+export { index as examples, hints, index$1 as schemas };

package/dist/dev.js

@@ -0,0 +1 @@
+"use strict";var e,t=Object.defineProperty,i=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,s=Object.prototype.hasOwnProperty,n=(e,i)=>{for(var r in i)t(e,r,{get:i[r],enumerable:!0})},a={};n(a,{examples:()=>c,hints:()=>v,schemas:()=>o}),module.exports=(e=a,((e,n,a,o)=>{if(n&&"object"==typeof n||"function"==typeof n)for(let p of r(n))s.call(e,p)||p===a||t(e,p,{get:()=>n[p],enumerable:!(o=i(n,p))||o.enumerable});return e})(t({},"__esModule",{value:!0}),e));var o={};n(o,{SettingsSchema:()=>d,settings:()=>l});var p=require("@walkeros/core/dev"),g=require("@walkeros/core/dev"),d=g.z.object({fields:g.z.array(g.z.union([g.z.string().describe('Dot-notation path: "ingest.ip", "event.data.userId"'),g.z.object({key:g.z.string().optional().describe("Source property path"),value:g.z.unknown().optional().describe("Static value or fallback"),fn:g.z.string().optional().describe("$code: function for value transformation")}).describe("Mapping value config for computed fields")])).describe("Fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }."),output:g.z.string().optional().describe('Dot-notation path where hash is stored on the event. Default: "user.hash"'),length:g.z.number().int().positive().optional().describe("Truncate hash to this length. Default: full 64-char SHA-256 hash")}).describe("Fingerprint transformer: generates deterministic user hashes from event fields"),l=(0,p.zodToSchema)(d),c={};n(c,{step:()=>u});var u={};n(u,{ipAnonymization:()=>h,missingFields:()=>f,serverFingerprint:()=>m});var m={title:"Server fingerprint",description:"Standard server fingerprint using ingest.ip and ingest.userAgent. Requires source config.ingest.",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"}}}]]},f={public:!1,description:"Graceful handling when ingest is missing - fields resolve to empty strings, 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"}}}]]},h={title:"IP anonymization",description:'Privacy-preserving fingerprint using key+fn pattern: fn truncates IP to /24 subnet before hashing, so 10.0.42.* users share a hash. Config: fields: [{ key: "ingest.ip", fn: ip => ip.replace(/\\.\\d+$/, ".0") }, "ingest.userAgent"]',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"}}}]]},v={"ingest-prerequisite":{text:"Fields starting with ingest.* require the server source to have config.ingest configured. Without it, ingest is undefined and all ingest.* fields resolve to empty strings — the hash is still generated but not unique. Always pair this transformer with a source that extracts request metadata.",code:[{lang:"json",code:JSON.stringify({sources:{express:{package:"@walkeros/server-source-express",config:{settings:{port:8080},ingest:{ip:"req.ip",userAgent:"req.headers.user-agent",origin:"req.headers.origin"}}}},transformers:{fingerprint:{package:"@walkeros/server-transformer-fingerprint",config:{settings:{fields:["ingest.ip","ingest.userAgent"],output:"user.hash",length:16}}}}},null,2)}]},"fields-overview":{text:"Fields resolve from { event, ingest } via walkerOS mapping. Common patterns: ingest.ip (client IP), ingest.userAgent (browser UA), event.data.* (any event property). For time-based rotation use fn fields: daily rotation with toISOString().slice(0,10), monthly with getDate(). Order matters — same fields in different order produce different hashes. Use { key, fn } objects to transform before hashing (e.g., IP anonymization via the ipAnonymization step example)."}};//# sourceMappingURL=dev.js.map

package/dist/dev.js.map

@@ -0,0 +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\n/**\n * Fingerprint transformer settings schema.\n *\n * Mirrors: types.ts FingerprintSettings\n */\nexport const SettingsSchema = z\n  .object({\n    fields: z\n      .array(\n        z.union([\n          z\n            .string()\n            .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\n                .unknown()\n                .optional()\n                .describe('Static value or fallback'),\n              fn: z\n                .string()\n                .optional()\n                .describe('$code: function for value transformation'),\n            })\n            .describe('Mapping value config for computed fields'),\n        ]),\n      )\n      .describe(\n        'Fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }.',\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: generates deterministic user hashes from event fields',\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    'Standard server fingerprint using ingest.ip and ingest.userAgent. Requires source config.ingest.',\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 - fields resolve to empty strings, 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    'Privacy-preserving fingerprint using key+fn pattern: ' +\n    'fn truncates IP to /24 subnet before hashing, so 10.0.42.* users share a hash. ' +\n    'Config: fields: [{ key: \"ingest.ip\", fn: ip => ip.replace(/\\\\.\\\\d+$/, \".0\") }, \"ingest.userAgent\"]',\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: 'Fields starting with ingest.* require the server source to have config.ingest configured. Without it, ingest is undefined and all ingest.* fields resolve to empty strings — the hash is still generated but not unique. Always pair this transformer with a source that extracts request metadata.',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            sources: {\n              express: {\n                package: '@walkeros/server-source-express',\n                config: {\n                  settings: { port: 8080 },\n                  ingest: {\n                    ip: 'req.ip',\n                    userAgent: 'req.headers.user-agent',\n                    origin: 'req.headers.origin',\n                  },\n                },\n              },\n            },\n            transformers: {\n              fingerprint: {\n                package: '@walkeros/server-transformer-fingerprint',\n                config: {\n                  settings: {\n                    fields: ['ingest.ip', 'ingest.userAgent'],\n                    output: 'user.hash',\n                    length: 16,\n                  },\n                },\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'fields-overview': {\n    text: 'Fields resolve from { event, ingest } via walkerOS mapping. Common patterns: ingest.ip (client IP), ingest.userAgent (browser UA), event.data.* (any event property). For time-based rotation use fn fields: daily rotation with toISOString().slice(0,10), monthly with getDate(). Order matters — same fields in different order produce different hashes. Use { key, fn } objects to transform before hashing (e.g., IP anonymization via the ipAnonymization step example).',\n  },\n};\n"],"mappings":"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","names":["import_dev"]}

package/dist/dev.mjs

@@ -0,0 +1 @@
+var e=Object.defineProperty,t=(t,i)=>{for(var r in i)e(t,r,{get:i[r],enumerable:!0})},i={};t(i,{SettingsSchema:()=>n,settings:()=>a});import{zodToSchema as r}from"@walkeros/core/dev";import{z as s}from"@walkeros/core/dev";var n=s.object({fields:s.array(s.union([s.string().describe('Dot-notation path: "ingest.ip", "event.data.userId"'),s.object({key:s.string().optional().describe("Source property path"),value:s.unknown().optional().describe("Static value or fallback"),fn:s.string().optional().describe("$code: function for value transformation")}).describe("Mapping value config for computed fields")])).describe("Fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }."),output:s.string().optional().describe('Dot-notation path where hash is stored on the event. Default: "user.hash"'),length:s.number().int().positive().optional().describe("Truncate hash to this length. Default: full 64-char SHA-256 hash")}).describe("Fingerprint transformer: generates deterministic user hashes from event fields"),a=r(n),o={};t(o,{step:()=>g});var g={};t(g,{ipAnonymization:()=>l,missingFields:()=>d,serverFingerprint:()=>p});var p={title:"Server fingerprint",description:"Standard server fingerprint using ingest.ip and ingest.userAgent. Requires source config.ingest.",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"}}}]]},d={public:!1,description:"Graceful handling when ingest is missing - fields resolve to empty strings, 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"}}}]]},l={title:"IP anonymization",description:'Privacy-preserving fingerprint using key+fn pattern: fn truncates IP to /24 subnet before hashing, so 10.0.42.* users share a hash. Config: fields: [{ key: "ingest.ip", fn: ip => ip.replace(/\\.\\d+$/, ".0") }, "ingest.userAgent"]',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"}}}]]},c={"ingest-prerequisite":{text:"Fields starting with ingest.* require the server source to have config.ingest configured. Without it, ingest is undefined and all ingest.* fields resolve to empty strings — the hash is still generated but not unique. Always pair this transformer with a source that extracts request metadata.",code:[{lang:"json",code:JSON.stringify({sources:{express:{package:"@walkeros/server-source-express",config:{settings:{port:8080},ingest:{ip:"req.ip",userAgent:"req.headers.user-agent",origin:"req.headers.origin"}}}},transformers:{fingerprint:{package:"@walkeros/server-transformer-fingerprint",config:{settings:{fields:["ingest.ip","ingest.userAgent"],output:"user.hash",length:16}}}}},null,2)}]},"fields-overview":{text:"Fields resolve from { event, ingest } via walkerOS mapping. Common patterns: ingest.ip (client IP), ingest.userAgent (browser UA), event.data.* (any event property). For time-based rotation use fn fields: daily rotation with toISOString().slice(0,10), monthly with getDate(). Order matters — same fields in different order produce different hashes. Use { key, fn } objects to transform before hashing (e.g., IP anonymization via the ipAnonymization step example)."}};export{o as examples,c as hints,i as schemas};//# sourceMappingURL=dev.mjs.map

package/dist/dev.mjs.map

@@ -0,0 +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\n/**\n * Fingerprint transformer settings schema.\n *\n * Mirrors: types.ts FingerprintSettings\n */\nexport const SettingsSchema = z\n  .object({\n    fields: z\n      .array(\n        z.union([\n          z\n            .string()\n            .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\n                .unknown()\n                .optional()\n                .describe('Static value or fallback'),\n              fn: z\n                .string()\n                .optional()\n                .describe('$code: function for value transformation'),\n            })\n            .describe('Mapping value config for computed fields'),\n        ]),\n      )\n      .describe(\n        'Fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }.',\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: generates deterministic user hashes from event fields',\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    'Standard server fingerprint using ingest.ip and ingest.userAgent. Requires source config.ingest.',\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 - fields resolve to empty strings, 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    'Privacy-preserving fingerprint using key+fn pattern: ' +\n    'fn truncates IP to /24 subnet before hashing, so 10.0.42.* users share a hash. ' +\n    'Config: fields: [{ key: \"ingest.ip\", fn: ip => ip.replace(/\\\\.\\\\d+$/, \".0\") }, \"ingest.userAgent\"]',\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: 'Fields starting with ingest.* require the server source to have config.ingest configured. Without it, ingest is undefined and all ingest.* fields resolve to empty strings — the hash is still generated but not unique. Always pair this transformer with a source that extracts request metadata.',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            sources: {\n              express: {\n                package: '@walkeros/server-source-express',\n                config: {\n                  settings: { port: 8080 },\n                  ingest: {\n                    ip: 'req.ip',\n                    userAgent: 'req.headers.user-agent',\n                    origin: 'req.headers.origin',\n                  },\n                },\n              },\n            },\n            transformers: {\n              fingerprint: {\n                package: '@walkeros/server-transformer-fingerprint',\n                config: {\n                  settings: {\n                    fields: ['ingest.ip', 'ingest.userAgent'],\n                    output: 'user.hash',\n                    length: 16,\n                  },\n                },\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'fields-overview': {\n    text: 'Fields resolve from { event, ingest } via walkerOS mapping. Common patterns: ingest.ip (client IP), ingest.userAgent (browser UA), event.data.* (any event property). For time-based rotation use fn fields: daily rotation with toISOString().slice(0,10), monthly with getDate(). Order matters — same fields in different order produce different hashes. Use { key, fn } objects to transform before hashing (e.g., IP anonymization via the ipAnonymization step example).',\n  },\n};\n"],"mappings":"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","names":[]}

package/dist/index.d.mts

@@ -53,4 +53,4 @@ interface FingerprintSettings {
  */
 declare const transformerFingerprint: Transformer.Init<Transformer.Types<FingerprintSettings>>;
 
-export { type FingerprintSettings, transformerFingerprint };
+export { type FingerprintSettings, transformerFingerprint as default, transformerFingerprint };

package/dist/index.d.ts

@@ -53,4 +53,4 @@ interface FingerprintSettings {
  */
 declare const transformerFingerprint: Transformer.Init<Transformer.Types<FingerprintSettings>>;
 
-export { type FingerprintSettings, transformerFingerprint };
+export { type FingerprintSettings, transformerFingerprint as default, transformerFingerprint };

package/dist/index.js

@@ -1 +1 @@
-"use strict";var e,r=Object.defineProperty,t=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,n=Object.prototype.hasOwnProperty,a={};((e,t)=>{for(var o in t)r(e,o,{get:t[o],enumerable:!0})})(a,{transformerFingerprint:()=>l}),module.exports=(e=a,((e,a,s,i)=>{if(a&&"object"==typeof a||"function"==typeof a)for(let l of o(a))n.call(e,l)||l===s||r(e,l,{get:()=>a[l],enumerable:!(i=t(a,l))||i.enumerable});return e})(r({},"__esModule",{value:!0}),e));var s=require("@walkeros/core"),i=require("@walkeros/server-core"),l=e=>{const{config:r}=e,t=r.settings||{},o=t.fields||[],n=t.output||"user.hash",a=t.length;return{type:"fingerprint",config:r,async push(e,r){const{ingest:t,collector:l}=r,c={event:e,ingest:t},p=""+(await Promise.all(o.map(e=>(0,s.getMappingValue)(c,e,{collector:l})))).map(e=>String(null!=e?e:"")).join(""),u=await(0,i.getHashServer)(p,a);return(0,s.setByPath)(e,n,u)}}};//# sourceMappingURL=index.js.map
+"use strict";var e,r=Object.defineProperty,t=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,n=Object.prototype.hasOwnProperty,a={};((e,t)=>{for(var o in t)r(e,o,{get:t[o],enumerable:!0})})(a,{default:()=>l,transformerFingerprint:()=>l}),module.exports=(e=a,((e,a,s,i)=>{if(a&&"object"==typeof a||"function"==typeof a)for(let l of o(a))n.call(e,l)||l===s||r(e,l,{get:()=>a[l],enumerable:!(i=t(a,l))||i.enumerable});return e})(r({},"__esModule",{value:!0}),e));var s=require("@walkeros/core"),i=require("@walkeros/server-core"),l=e=>{const{config:r}=e,t=r.settings||{},o=t.fields||[],n=t.output||"user.hash",a=t.length;return{type:"fingerprint",config:r,async push(e,r){const{ingest:t,collector:l}=r,c={event:e,ingest:t},p=""+(await Promise.all(o.map(e=>(0,s.getMappingValue)(c,e,{collector:l})))).map(e=>String(e??"")).join(""),u=await(0,i.getHashServer)(p,a);return{event:(0,s.setByPath)(e,n,u)}}}};//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/transformer.ts"],"sourcesContent":["export { transformerFingerprint } from './transformer';\nexport type { FingerprintSettings } from './types';\n","import type { Mapping, Transformer } from '@walkeros/core';\nimport { getMappingValue, setByPath } from '@walkeros/core';\nimport { getHashServer } from '@walkeros/server-core';\nimport type { FingerprintSettings } from './types';\n\n/**\n * Fingerprint transformer - hash configurable fields for session continuity.\n *\n * Resolves fields from { event, ingest } source object using getMappingValue,\n * concatenates values in order, hashes with SHA-256, and stores at output path.\n *\n * @example\n * transformerFingerprint({\n *   config: {\n *     settings: {\n *       fields: [\n *         'ingest.ip',\n *         'ingest.userAgent',\n *         { fn: () => new Date().getDate() },\n *       ],\n *       output: 'user.hash',\n *       length: 16,\n *     },\n *   },\n * })\n */\nexport const transformerFingerprint: Transformer.Init<\n  Transformer.Types<FingerprintSettings>\n> = (context) => {\n  const { config } = context;\n  const settings = (config.settings || {}) as Partial<FingerprintSettings>;\n  const fields: Mapping.Value[] = settings.fields || [];\n  const output: string = settings.output || 'user.hash';\n  const length: number | undefined = settings.length;\n\n  return {\n    type: 'fingerprint',\n    config: config as Transformer.Config<\n      Transformer.Types<FingerprintSettings>\n    >,\n\n    async push(event, context) {\n      const { ingest, collector } = context;\n\n      // Build source object for field resolution\n      const source = { event, ingest };\n\n      // Resolve each field via mapping (maintains order)\n      const values = await Promise.all(\n        fields.map((field: Mapping.Value) =>\n          getMappingValue(source, field, { collector }),\n        ),\n      );\n\n      // Safe string concatenation: '' prefix + String() cast for each value\n      // '' prefix ensures we always have a string even if fields is empty\n      // String(v ?? '') handles undefined/null gracefully\n      const input = '' + values.map((v: unknown) => String(v ?? '')).join('');\n\n      // Hash and store at output path\n      const hash = await getHashServer(input, length);\n      return setByPath(event, output, hash);\n    },\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACCA,kBAA2C;AAC3C,yBAA8B;AAwBvB,IAAM,yBAET,CAAC,YAAY;AACf,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,WAAY,OAAO,YAAY,CAAC;AACtC,QAAM,SAA0B,SAAS,UAAU,CAAC;AACpD,QAAM,SAAiB,SAAS,UAAU;AAC1C,QAAM,SAA6B,SAAS;AAE5C,SAAO;AAAA,IACL,MAAM;AAAA,IACN;AAAA,IAIA,MAAM,KAAK,OAAOA,UAAS;AACzB,YAAM,EAAE,QAAQ,UAAU,IAAIA;AAG9B,YAAM,SAAS,EAAE,OAAO,OAAO;AAG/B,YAAM,SAAS,MAAM,QAAQ;AAAA,QAC3B,OAAO;AAAA,UAAI,CAAC,cACV,6BAAgB,QAAQ,OAAO,EAAE,UAAU,CAAC;AAAA,QAC9C;AAAA,MACF;AAKA,YAAM,QAAQ,KAAK,OAAO,IAAI,CAAC,MAAe,OAAO,gBAAK,EAAE,CAAC,EAAE,KAAK,EAAE;AAGtE,YAAM,OAAO,UAAM,kCAAc,OAAO,MAAM;AAC9C,iBAAO,uBAAU,OAAO,QAAQ,IAAI;AAAA,IACtC;AAAA,EACF;AACF;","names":["context"]}
+{"version":3,"sources":["../src/index.ts","../src/transformer.ts"],"sourcesContent":["export { transformerFingerprint } from './transformer';\nexport type { FingerprintSettings } from './types';\n\nexport { transformerFingerprint as default } from './transformer';\n","import type { Mapping, Transformer } from '@walkeros/core';\nimport { getMappingValue, setByPath } from '@walkeros/core';\nimport { getHashServer } from '@walkeros/server-core';\nimport type { FingerprintSettings } from './types';\n\n/**\n * Fingerprint transformer - hash configurable fields for session continuity.\n *\n * Resolves fields from { event, ingest } source object using getMappingValue,\n * concatenates values in order, hashes with SHA-256, and stores at output path.\n *\n * @example\n * transformerFingerprint({\n *   config: {\n *     settings: {\n *       fields: [\n *         'ingest.ip',\n *         'ingest.userAgent',\n *         { fn: () => new Date().getDate() },\n *       ],\n *       output: 'user.hash',\n *       length: 16,\n *     },\n *   },\n * })\n */\nexport const transformerFingerprint: Transformer.Init<\n  Transformer.Types<FingerprintSettings>\n> = (context) => {\n  const { config } = context;\n  const settings = (config.settings || {}) as Partial<FingerprintSettings>;\n  const fields: Mapping.Value[] = settings.fields || [];\n  const output: string = settings.output || 'user.hash';\n  const length: number | undefined = settings.length;\n\n  return {\n    type: 'fingerprint',\n    config: config as Transformer.Config<\n      Transformer.Types<FingerprintSettings>\n    >,\n\n    async push(event, context) {\n      const { ingest, collector } = context;\n\n      // Build source object for field resolution\n      const source = { event, ingest };\n\n      // Resolve each field via mapping (maintains order)\n      const values = await Promise.all(\n        fields.map((field: Mapping.Value) =>\n          getMappingValue(source, field, { collector }),\n        ),\n      );\n\n      // Safe string concatenation: '' prefix + String() cast for each value\n      // '' prefix ensures we always have a string even if fields is empty\n      // String(v ?? '') handles undefined/null gracefully\n      const input = '' + values.map((v: unknown) => String(v ?? '')).join('');\n\n      // Hash and store at output path\n      const hash = await getHashServer(input, length);\n      return { event: setByPath(event, output, hash) };\n    },\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACCA,kBAA2C;AAC3C,yBAA8B;AAwBvB,IAAM,yBAET,CAAC,YAAY;AACf,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,WAAY,OAAO,YAAY,CAAC;AACtC,QAAM,SAA0B,SAAS,UAAU,CAAC;AACpD,QAAM,SAAiB,SAAS,UAAU;AAC1C,QAAM,SAA6B,SAAS;AAE5C,SAAO;AAAA,IACL,MAAM;AAAA,IACN;AAAA,IAIA,MAAM,KAAK,OAAOA,UAAS;AACzB,YAAM,EAAE,QAAQ,UAAU,IAAIA;AAG9B,YAAM,SAAS,EAAE,OAAO,OAAO;AAG/B,YAAM,SAAS,MAAM,QAAQ;AAAA,QAC3B,OAAO;AAAA,UAAI,CAAC,cACV,6BAAgB,QAAQ,OAAO,EAAE,UAAU,CAAC;AAAA,QAC9C;AAAA,MACF;AAKA,YAAM,QAAQ,KAAK,OAAO,IAAI,CAAC,MAAe,OAAO,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE;AAGtE,YAAM,OAAO,UAAM,kCAAc,OAAO,MAAM;AAC9C,aAAO,EAAE,WAAO,uBAAU,OAAO,QAAQ,IAAI,EAAE;AAAA,IACjD;AAAA,EACF;AACF;","names":["context"]}

package/dist/index.mjs

@@ -1 +1 @@
-import{getMappingValue as r,setByPath as e}from"@walkeros/core";import{getHashServer as t}from"@walkeros/server-core";var o=o=>{const{config:n}=o,i=n.settings||{},s=i.fields||[],a=i.output||"user.hash",l=i.length;return{type:"fingerprint",config:n,async push(o,n){const{ingest:i,collector:c}=n,p={event:o,ingest:i},g=""+(await Promise.all(s.map(e=>r(p,e,{collector:c})))).map(r=>String(null!=r?r:"")).join(""),m=await t(g,l);return e(o,a,m)}}};export{o as transformerFingerprint};//# sourceMappingURL=index.mjs.map
+import{getMappingValue as e,setByPath as t}from"@walkeros/core";import{getHashServer as r}from"@walkeros/server-core";var o=o=>{const{config:n}=o,s=n.settings||{},i=s.fields||[],a=s.output||"user.hash",c=s.length;return{type:"fingerprint",config:n,async push(o,n){const{ingest:s,collector:l}=n,p={event:o,ingest:s},g=""+(await Promise.all(i.map(t=>e(p,t,{collector:l})))).map(e=>String(e??"")).join(""),f=await r(g,c);return{event:t(o,a,f)}}}};export{o as default,o as transformerFingerprint};//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/transformer.ts"],"sourcesContent":["import type { Mapping, Transformer } from '@walkeros/core';\nimport { getMappingValue, setByPath } from '@walkeros/core';\nimport { getHashServer } from '@walkeros/server-core';\nimport type { FingerprintSettings } from './types';\n\n/**\n * Fingerprint transformer - hash configurable fields for session continuity.\n *\n * Resolves fields from { event, ingest } source object using getMappingValue,\n * concatenates values in order, hashes with SHA-256, and stores at output path.\n *\n * @example\n * transformerFingerprint({\n *   config: {\n *     settings: {\n *       fields: [\n *         'ingest.ip',\n *         'ingest.userAgent',\n *         { fn: () => new Date().getDate() },\n *       ],\n *       output: 'user.hash',\n *       length: 16,\n *     },\n *   },\n * })\n */\nexport const transformerFingerprint: Transformer.Init<\n  Transformer.Types<FingerprintSettings>\n> = (context) => {\n  const { config } = context;\n  const settings = (config.settings || {}) as Partial<FingerprintSettings>;\n  const fields: Mapping.Value[] = settings.fields || [];\n  const output: string = settings.output || 'user.hash';\n  const length: number | undefined = settings.length;\n\n  return {\n    type: 'fingerprint',\n    config: config as Transformer.Config<\n      Transformer.Types<FingerprintSettings>\n    >,\n\n    async push(event, context) {\n      const { ingest, collector } = context;\n\n      // Build source object for field resolution\n      const source = { event, ingest };\n\n      // Resolve each field via mapping (maintains order)\n      const values = await Promise.all(\n        fields.map((field: Mapping.Value) =>\n          getMappingValue(source, field, { collector }),\n        ),\n      );\n\n      // Safe string concatenation: '' prefix + String() cast for each value\n      // '' prefix ensures we always have a string even if fields is empty\n      // String(v ?? '') handles undefined/null gracefully\n      const input = '' + values.map((v: unknown) => String(v ?? '')).join('');\n\n      // Hash and store at output path\n      const hash = await getHashServer(input, length);\n      return setByPath(event, output, hash);\n    },\n  };\n};\n"],"mappings":";AACA,SAAS,iBAAiB,iBAAiB;AAC3C,SAAS,qBAAqB;AAwBvB,IAAM,yBAET,CAAC,YAAY;AACf,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,WAAY,OAAO,YAAY,CAAC;AACtC,QAAM,SAA0B,SAAS,UAAU,CAAC;AACpD,QAAM,SAAiB,SAAS,UAAU;AAC1C,QAAM,SAA6B,SAAS;AAE5C,SAAO;AAAA,IACL,MAAM;AAAA,IACN;AAAA,IAIA,MAAM,KAAK,OAAOA,UAAS;AACzB,YAAM,EAAE,QAAQ,UAAU,IAAIA;AAG9B,YAAM,SAAS,EAAE,OAAO,OAAO;AAG/B,YAAM,SAAS,MAAM,QAAQ;AAAA,QAC3B,OAAO;AAAA,UAAI,CAAC,UACV,gBAAgB,QAAQ,OAAO,EAAE,UAAU,CAAC;AAAA,QAC9C;AAAA,MACF;AAKA,YAAM,QAAQ,KAAK,OAAO,IAAI,CAAC,MAAe,OAAO,gBAAK,EAAE,CAAC,EAAE,KAAK,EAAE;AAGtE,YAAM,OAAO,MAAM,cAAc,OAAO,MAAM;AAC9C,aAAO,UAAU,OAAO,QAAQ,IAAI;AAAA,IACtC;AAAA,EACF;AACF;","names":["context"]}
+{"version":3,"sources":["../src/transformer.ts"],"sourcesContent":["import type { Mapping, Transformer } from '@walkeros/core';\nimport { getMappingValue, setByPath } from '@walkeros/core';\nimport { getHashServer } from '@walkeros/server-core';\nimport type { FingerprintSettings } from './types';\n\n/**\n * Fingerprint transformer - hash configurable fields for session continuity.\n *\n * Resolves fields from { event, ingest } source object using getMappingValue,\n * concatenates values in order, hashes with SHA-256, and stores at output path.\n *\n * @example\n * transformerFingerprint({\n *   config: {\n *     settings: {\n *       fields: [\n *         'ingest.ip',\n *         'ingest.userAgent',\n *         { fn: () => new Date().getDate() },\n *       ],\n *       output: 'user.hash',\n *       length: 16,\n *     },\n *   },\n * })\n */\nexport const transformerFingerprint: Transformer.Init<\n  Transformer.Types<FingerprintSettings>\n> = (context) => {\n  const { config } = context;\n  const settings = (config.settings || {}) as Partial<FingerprintSettings>;\n  const fields: Mapping.Value[] = settings.fields || [];\n  const output: string = settings.output || 'user.hash';\n  const length: number | undefined = settings.length;\n\n  return {\n    type: 'fingerprint',\n    config: config as Transformer.Config<\n      Transformer.Types<FingerprintSettings>\n    >,\n\n    async push(event, context) {\n      const { ingest, collector } = context;\n\n      // Build source object for field resolution\n      const source = { event, ingest };\n\n      // Resolve each field via mapping (maintains order)\n      const values = await Promise.all(\n        fields.map((field: Mapping.Value) =>\n          getMappingValue(source, field, { collector }),\n        ),\n      );\n\n      // Safe string concatenation: '' prefix + String() cast for each value\n      // '' prefix ensures we always have a string even if fields is empty\n      // String(v ?? '') handles undefined/null gracefully\n      const input = '' + values.map((v: unknown) => String(v ?? '')).join('');\n\n      // Hash and store at output path\n      const hash = await getHashServer(input, length);\n      return { event: setByPath(event, output, hash) };\n    },\n  };\n};\n"],"mappings":";AACA,SAAS,iBAAiB,iBAAiB;AAC3C,SAAS,qBAAqB;AAwBvB,IAAM,yBAET,CAAC,YAAY;AACf,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,WAAY,OAAO,YAAY,CAAC;AACtC,QAAM,SAA0B,SAAS,UAAU,CAAC;AACpD,QAAM,SAAiB,SAAS,UAAU;AAC1C,QAAM,SAA6B,SAAS;AAE5C,SAAO;AAAA,IACL,MAAM;AAAA,IACN;AAAA,IAIA,MAAM,KAAK,OAAOA,UAAS;AACzB,YAAM,EAAE,QAAQ,UAAU,IAAIA;AAG9B,YAAM,SAAS,EAAE,OAAO,OAAO;AAG/B,YAAM,SAAS,MAAM,QAAQ;AAAA,QAC3B,OAAO;AAAA,UAAI,CAAC,UACV,gBAAgB,QAAQ,OAAO,EAAE,UAAU,CAAC;AAAA,QAC9C;AAAA,MACF;AAKA,YAAM,QAAQ,KAAK,OAAO,IAAI,CAAC,MAAe,OAAO,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE;AAGtE,YAAM,OAAO,MAAM,cAAc,OAAO,MAAM;AAC9C,aAAO,EAAE,OAAO,UAAU,OAAO,QAAQ,IAAI,EAAE;AAAA,IACjD;AAAA,EACF;AACF;","names":["context"]}

package/dist/walkerOS.json

@@ -0,0 +1,223 @@
+{
+  "$meta": {
+    "package": "@walkeros/server-transformer-fingerprint",
+    "version": "4.0.1-next-1778183328892",
+    "type": "transformer",
+    "platform": [
+      "server"
+    ],
+    "docs": "https://www.walkeros.io/docs/transformers/fingerprint",
+    "source": "https://github.com/elbwalker/walkerOS/tree/main/packages/server/transformers/fingerprint/src"
+  },
+  "schemas": {
+    "settings": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "type": "object",
+      "properties": {
+        "fields": {
+          "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 for value transformation",
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Mapping value config for computed fields"
+              }
+            ]
+          },
+          "description": "Fields to include in hash (order matters). Each resolved via getMappingValue with source { event, ingest }."
+        },
+        "output": {
+          "description": "Dot-notation path where hash is stored on the event. Default: \"user.hash\"",
+          "type": "string"
+        },
+        "length": {
+          "description": "Truncate hash to this length. Default: full 64-char SHA-256 hash",
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "fields"
+      ],
+      "additionalProperties": false,
+      "description": "Fingerprint transformer: generates deterministic user hashes from event fields"
+    }
+  },
+  "examples": {
+    "step": {
+      "ipAnonymization": {
+        "title": "IP anonymization",
+        "description": "Privacy-preserving fingerprint using key+fn pattern: fn truncates IP to /24 subnet before hashing, so 10.0.42.* users share a hash. Config: fields: [{ key: \"ingest.ip\", fn: ip => ip.replace(/\\.\\d+$/, \".0\") }, \"ingest.userAgent\"]",
+        "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"
+                }
+              }
+            }
+          ]
+        ]
+      },
+      "missingFields": {
+        "public": false,
+        "description": "Graceful handling when ingest is missing - fields resolve to empty strings, 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"
+                }
+              }
+            }
+          ]
+        ]
+      },
+      "serverFingerprint": {
+        "title": "Server fingerprint",
+        "description": "Standard server fingerprint using ingest.ip and ingest.userAgent. Requires source config.ingest.",
+        "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"
+                }
+              }
+            }
+          ]
+        ]
+      }
+    }
+  },
+  "hints": {
+    "ingest-prerequisite": {
+      "text": "Fields starting with ingest.* require the server source to have config.ingest configured. Without it, ingest is undefined and all ingest.* fields resolve to empty strings — the hash is still generated but not unique. Always pair this transformer with a source that extracts request metadata.",
+      "code": [
+        {
+          "lang": "json",
+          "code": "{\n  \"sources\": {\n    \"express\": {\n      \"package\": \"@walkeros/server-source-express\",\n      \"config\": {\n        \"settings\": {\n          \"port\": 8080\n        },\n        \"ingest\": {\n          \"ip\": \"req.ip\",\n          \"userAgent\": \"req.headers.user-agent\",\n          \"origin\": \"req.headers.origin\"\n        }\n      }\n    }\n  },\n  \"transformers\": {\n    \"fingerprint\": {\n      \"package\": \"@walkeros/server-transformer-fingerprint\",\n      \"config\": {\n        \"settings\": {\n          \"fields\": [\n            \"ingest.ip\",\n            \"ingest.userAgent\"\n          ],\n          \"output\": \"user.hash\",\n          \"length\": 16\n        }\n      }\n    }\n  }\n}"
+        }
+      ]
+    },
+    "fields-overview": {
+      "text": "Fields resolve from { event, ingest } via walkerOS mapping. Common patterns: ingest.ip (client IP), ingest.userAgent (browser UA), event.data.* (any event property). For time-based rotation use fn fields: daily rotation with toISOString().slice(0,10), monthly with getDate(). Order matters — same fields in different order produce different hashes. Use { key, fn } objects to transform before hashing (e.g., IP anonymization via the ipAnonymization step example)."
+    }
+  }
+}

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.0.0",
+  "version": "4.0.1-next-1778183328892",
   "license": "MIT",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -11,7 +11,8 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
-    }
+    },
+    "./walkerOS.json": "./dist/walkerOS.json"
   },
   "files": [
     "dist/**"
@@ -20,17 +21,14 @@
     "build": "tsup --silent",
     "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
     "dev": "jest --watchAll --colors",
-    "lint": "tsc --noEmit && eslint \"**/*.ts*\"",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"**/*.ts*\"",
     "test": "jest",
     "update": "npx npm-check-updates -u && npm update"
   },
-  "peerDependencies": {
-    "@walkeros/core": "^1.0.0",
-    "@walkeros/server-core": "^1.0.0"
-  },
   "devDependencies": {
-    "@walkeros/core": "1.0.0",
-    "@walkeros/server-core": "1.0.0"
+    "@walkeros/core": "4.0.1-next-1778183328892",
+    "@walkeros/server-core": "4.0.1-next-1778183328892"
   },
   "repository": {
     "url": "git+https://github.com/elbwalker/walkerOS.git",
@@ -41,8 +39,14 @@
   "bugs": {
     "url": "https://github.com/elbwalker/walkerOS/issues"
   },
+  "walkerOS": {
+    "type": "transformer",
+    "platform": [
+      "server"
+    ],
+    "docs": "https://www.walkeros.io/docs/transformers/fingerprint"
+  },
   "keywords": [
-    "walker",
     "walkerOS",
     "transformer",
     "fingerprint",
@@ -54,5 +58,9 @@
       "type": "GitHub Sponsors",
       "url": "https://github.com/sponsors/elbwalker"
     }
-  ]
+  ],
+  "dependencies": {
+    "@walkeros/core": "4.0.1-next-1778183328892",
+    "@walkeros/server-core": "4.0.1-next-1778183328892"
+  }
 }