@walkeros/core 0.4.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="left">
-  <a href="https://elbwalker.com">
-    <img title="elbwalker" src="https://www.elbwalker.com/img/elbwalker_logo.png" width="256px"/>
+  <a href="https://www.walkeros.io">
+    <img title="elbwalker" src="https://www.walkeros.io/img/elbwalker_logo.png" width="256px"/>
   </a>
 </p>
 
@@ -15,7 +15,35 @@ data manipulation, validation, mapping, and more.
 
 ## Installation
 
-Import the core utilities directly from the `@walkeros/core` package:
+```bash
+npm install @walkeros/core
+```
+
+## Quick Start
+
+The core package provides types and utilities used across walkerOS. In a Flow
+configuration:
+
+```json
+{
+  "version": 1,
+  "flows": {
+    "default": {
+      "web": {},
+      "destinations": {
+        "api": {
+          "package": "@walkeros/web-destination-api",
+          "config": {
+            "url": "https://collect.example.com/events"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Import utilities directly:
 
 ```ts
 import { assign, anonymizeIP, getMappingValue } from '@walkeros/core';
@@ -119,7 +147,7 @@ getId(10); // Returns 10-character string
 
 `getMappingValue(event: WalkerOS.Event, mapping: Mapping.Data, options?: Mapping.Options): Promise<WalkerOS.Property | undefined>`
 extracts values from events using
-[mapping configurations](https://www.elbwalker.com/docs/destinations/event-mapping).
+[mapping configurations](https://www.walkeros.io/docs/destinations/event-mapping).
 
 ```ts
 // Simple path mapping
@@ -300,13 +328,22 @@ validates event structure and throws on invalid events.
 
 Validates that values conform to walkerOS property types.
 
----
+## Type Definitions
+
+See [src/types/](./src/types/) for TypeScript interfaces:
+
+- [event.ts](./src/types/event.ts) - Event structure
+- [destination.ts](./src/types/destination.ts) - Destination interface
+- [source.ts](./src/types/source.ts) - Source interface
+- [mapping.ts](./src/types/mapping.ts) - Mapping configuration
 
-For platform-specific utilities, see:
+## Related
 
-- [Web Core](https://www.elbwalker.com/docs/core/web) - Browser-specific
+- [Website Documentation](https://www.walkeros.io/docs/)
+- [Collector Package](../collector/) - Event processing engine
+- [Web Core](https://www.walkeros.io/docs/sources/web/) - Browser-specific
   functions
-- [Server Core](https://www.elbwalker.com/docs/core/server) - Node.js server
+- [Server Core](https://www.walkeros.io/docs/sources/server/) - Node.js server
   functions
 
 ## Contribute

package/dist/dev.d.mts

@@ -3371,7 +3371,7 @@ declare namespace source {
  * Mirrors: types/flow.ts
  * Purpose: Runtime validation and JSON Schema generation for Flow configurations
  *
- * The Flow system provides unified configuration across all walkerOS environments.
+ * The Flow system provides unified configuration across all walkerOS flows.
  * These schemas enable:
  * - Runtime validation of config files
  * - Clear error messages for configuration issues
@@ -3389,6 +3389,33 @@ declare namespace source {
  * Used in Setup.variables and Config.env.
  */
 declare const PrimitiveSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+/**
+ * Variables schema for interpolation.
+ */
+declare const VariablesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+/**
+ * Definitions schema for reusable configurations.
+ */
+declare const DefinitionsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/**
+ * Packages schema for build configuration.
+ */
+declare const PackagesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    version: z.ZodOptional<z.ZodString>;
+    imports: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/**
+ * Web platform configuration schema.
+ */
+declare const WebSchema: z.ZodObject<{
+    windowCollector: z.ZodOptional<z.ZodString>;
+    windowElb: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Server platform configuration schema.
+ */
+declare const ServerSchema: z.ZodObject<{}, z.core.$loose>;
 /**
  * Source reference schema.
  *
@@ -3398,9 +3425,12 @@ declare const PrimitiveSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.
  */
 declare const SourceReferenceSchema: z.ZodObject<{
     package: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
     config: z.ZodOptional<z.ZodUnknown>;
     env: z.ZodOptional<z.ZodUnknown>;
     primary: z.ZodOptional<z.ZodBoolean>;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    definitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 /**
  * Destination reference schema.
@@ -3411,66 +3441,96 @@ declare const SourceReferenceSchema: z.ZodObject<{
  */
 declare const DestinationReferenceSchema: z.ZodObject<{
     package: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
     config: z.ZodOptional<z.ZodUnknown>;
     env: z.ZodOptional<z.ZodUnknown>;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    definitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 /**
- * Flow environment configuration schema.
+ * Single flow configuration schema.
  *
  * @remarks
- * Represents a single deployment environment (e.g., web_prod, server_stage).
- * Uses `.passthrough()` to allow package-specific extensions (build, docker, etc.).
+ * Represents a single deployment target (e.g., web_prod, server_stage).
+ * Platform is determined by presence of `web` or `server` key.
+ * Exactly one must be present.
  */
 declare const ConfigSchema: z.ZodObject<{
-    platform: z.ZodEnum<{
-        web: "web";
-        server: "server";
-    }>;
+    web: z.ZodOptional<z.ZodObject<{
+        windowCollector: z.ZodOptional<z.ZodString>;
+        windowElb: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    server: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
     sources: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         package: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
         config: z.ZodOptional<z.ZodUnknown>;
         env: z.ZodOptional<z.ZodUnknown>;
         primary: z.ZodOptional<z.ZodBoolean>;
+        variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        definitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>>;
     destinations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         package: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
         config: z.ZodOptional<z.ZodUnknown>;
         env: z.ZodOptional<z.ZodUnknown>;
+        variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        definitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>>;
     collector: z.ZodOptional<z.ZodUnknown>;
-    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-}, z.core.$loose>;
+    packages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        version: z.ZodOptional<z.ZodString>;
+        imports: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    definitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
 /**
  * Flow setup schema - root configuration.
  *
  * @remarks
  * This is the complete schema for walkeros.config.json files.
- * Contains multiple named environments with shared variables and definitions.
+ * Contains multiple named flows with shared variables and definitions.
  */
 declare const SetupSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     $schema: z.ZodOptional<z.ZodString>;
     variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     definitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    environments: z.ZodRecord<z.ZodString, z.ZodObject<{
-        platform: z.ZodEnum<{
-            web: "web";
-            server: "server";
-        }>;
+    flows: z.ZodRecord<z.ZodString, z.ZodObject<{
+        web: z.ZodOptional<z.ZodObject<{
+            windowCollector: z.ZodOptional<z.ZodString>;
+            windowElb: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        server: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
         sources: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             package: z.ZodString;
+            code: z.ZodOptional<z.ZodString>;
             config: z.ZodOptional<z.ZodUnknown>;
             env: z.ZodOptional<z.ZodUnknown>;
             primary: z.ZodOptional<z.ZodBoolean>;
+            variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+            definitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>>;
         destinations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             package: z.ZodString;
+            code: z.ZodOptional<z.ZodString>;
             config: z.ZodOptional<z.ZodUnknown>;
             env: z.ZodOptional<z.ZodUnknown>;
+            variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+            definitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>>;
         collector: z.ZodOptional<z.ZodUnknown>;
-        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    }, z.core.$loose>>;
+        packages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            version: z.ZodOptional<z.ZodString>;
+            imports: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        definitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
  * Parse and validate Flow.Setup configuration.
@@ -3486,7 +3546,7 @@ declare const SetupSchema: z.ZodObject<{
  *
  * const raw = JSON.parse(readFileSync('walkeros.config.json', 'utf8'));
  * const config = parseSetup(raw);
- * console.log(`Found ${Object.keys(config.environments).length} environments`);
+ * console.log(`Found ${Object.keys(config.flows).length} flows`);
  * ```
  */
 declare function parseSetup(data: unknown): z.infer<typeof SetupSchema>;
@@ -3510,31 +3570,48 @@ declare function parseSetup(data: unknown): z.infer<typeof SetupSchema>;
  */
 declare function safeParseSetup(data: unknown): z.ZodSafeParseResult<{
     version: 1;
-    environments: Record<string, {
-        [x: string]: unknown;
-        platform: "web" | "server";
+    flows: Record<string, {
+        web?: {
+            windowCollector?: string | undefined;
+            windowElb?: string | undefined;
+        } | undefined;
+        server?: {
+            [x: string]: unknown;
+        } | undefined;
         sources?: Record<string, {
             package: string;
+            code?: string | undefined;
             config?: unknown;
             env?: unknown;
             primary?: boolean | undefined;
+            variables?: Record<string, string | number | boolean> | undefined;
+            definitions?: Record<string, unknown> | undefined;
         }> | undefined;
         destinations?: Record<string, {
             package: string;
+            code?: string | undefined;
             config?: unknown;
             env?: unknown;
+            variables?: Record<string, string | number | boolean> | undefined;
+            definitions?: Record<string, unknown> | undefined;
         }> | undefined;
         collector?: unknown;
-        env?: Record<string, string> | undefined;
+        packages?: Record<string, {
+            version?: string | undefined;
+            imports?: string[] | undefined;
+            path?: string | undefined;
+        }> | undefined;
+        variables?: Record<string, string | number | boolean> | undefined;
+        definitions?: Record<string, unknown> | undefined;
     }>;
     $schema?: string | undefined;
     variables?: Record<string, string | number | boolean> | undefined;
     definitions?: Record<string, unknown> | undefined;
 }>;
 /**
- * Parse and validate Flow.Config (single environment).
+ * Parse and validate Flow.Config (single flow).
  *
- * @param data - Raw JSON data for single environment
+ * @param data - Raw JSON data for single flow
  * @returns Validated Flow.Config object
  * @throws ZodError if validation fails
  *
@@ -3542,33 +3619,50 @@ declare function safeParseSetup(data: unknown): z.ZodSafeParseResult<{
  * ```typescript
  * import { parseConfig } from '@walkeros/core/dev';
  *
- * const envConfig = parseConfig(rawEnvData);
- * console.log(`Platform: ${envConfig.platform}`);
+ * const flowConfig = parseConfig(rawFlowData);
+ * console.log(`Platform: ${flowConfig.web ? 'web' : 'server'}`);
  * ```
  */
 declare function parseConfig(data: unknown): z.infer<typeof ConfigSchema>;
 /**
  * Safely parse Flow.Config without throwing.
  *
- * @param data - Raw JSON data for single environment
+ * @param data - Raw JSON data for single flow
  * @returns Success result with data or error result with issues
  */
 declare function safeParseConfig(data: unknown): z.ZodSafeParseResult<{
-    [x: string]: unknown;
-    platform: "web" | "server";
+    web?: {
+        windowCollector?: string | undefined;
+        windowElb?: string | undefined;
+    } | undefined;
+    server?: {
+        [x: string]: unknown;
+    } | undefined;
     sources?: Record<string, {
         package: string;
+        code?: string | undefined;
         config?: unknown;
         env?: unknown;
         primary?: boolean | undefined;
+        variables?: Record<string, string | number | boolean> | undefined;
+        definitions?: Record<string, unknown> | undefined;
     }> | undefined;
     destinations?: Record<string, {
         package: string;
+        code?: string | undefined;
         config?: unknown;
         env?: unknown;
+        variables?: Record<string, string | number | boolean> | undefined;
+        definitions?: Record<string, unknown> | undefined;
     }> | undefined;
     collector?: unknown;
-    env?: Record<string, string> | undefined;
+    packages?: Record<string, {
+        version?: string | undefined;
+        imports?: string[] | undefined;
+        path?: string | undefined;
+    }> | undefined;
+    variables?: Record<string, string | number | boolean> | undefined;
+    definitions?: Record<string, unknown> | undefined;
 }>;
 /**
  * Generate JSON Schema for Flow.Setup.
@@ -3595,7 +3689,7 @@ declare const setupJsonSchema: z.core.JSONSchema.JSONSchema;
  * Generate JSON Schema for Flow.Config.
  *
  * @remarks
- * Used for validating individual environment configurations.
+ * Used for validating individual flow configurations.
  *
  * @returns JSON Schema (Draft 7) representation of ConfigSchema
  */
@@ -3620,10 +3714,15 @@ declare const sourceReferenceJsonSchema: z.core.JSONSchema.JSONSchema;
 declare const destinationReferenceJsonSchema: z.core.JSONSchema.JSONSchema;
 
 declare const flow_ConfigSchema: typeof ConfigSchema;
+declare const flow_DefinitionsSchema: typeof DefinitionsSchema;
 declare const flow_DestinationReferenceSchema: typeof DestinationReferenceSchema;
+declare const flow_PackagesSchema: typeof PackagesSchema;
 declare const flow_PrimitiveSchema: typeof PrimitiveSchema;
+declare const flow_ServerSchema: typeof ServerSchema;
 declare const flow_SetupSchema: typeof SetupSchema;
 declare const flow_SourceReferenceSchema: typeof SourceReferenceSchema;
+declare const flow_VariablesSchema: typeof VariablesSchema;
+declare const flow_WebSchema: typeof WebSchema;
 declare const flow_configJsonSchema: typeof configJsonSchema;
 declare const flow_destinationReferenceJsonSchema: typeof destinationReferenceJsonSchema;
 declare const flow_parseConfig: typeof parseConfig;
@@ -3633,7 +3732,7 @@ declare const flow_safeParseSetup: typeof safeParseSetup;
 declare const flow_setupJsonSchema: typeof setupJsonSchema;
 declare const flow_sourceReferenceJsonSchema: typeof sourceReferenceJsonSchema;
 declare namespace flow {
-  export { flow_ConfigSchema as ConfigSchema, flow_DestinationReferenceSchema as DestinationReferenceSchema, flow_PrimitiveSchema as PrimitiveSchema, flow_SetupSchema as SetupSchema, flow_SourceReferenceSchema as SourceReferenceSchema, flow_configJsonSchema as configJsonSchema, flow_destinationReferenceJsonSchema as destinationReferenceJsonSchema, flow_parseConfig as parseConfig, flow_parseSetup as parseSetup, flow_safeParseConfig as safeParseConfig, flow_safeParseSetup as safeParseSetup, flow_setupJsonSchema as setupJsonSchema, flow_sourceReferenceJsonSchema as sourceReferenceJsonSchema };
+  export { flow_ConfigSchema as ConfigSchema, flow_DefinitionsSchema as DefinitionsSchema, flow_DestinationReferenceSchema as DestinationReferenceSchema, flow_PackagesSchema as PackagesSchema, flow_PrimitiveSchema as PrimitiveSchema, flow_ServerSchema as ServerSchema, flow_SetupSchema as SetupSchema, flow_SourceReferenceSchema as SourceReferenceSchema, flow_VariablesSchema as VariablesSchema, flow_WebSchema as WebSchema, flow_configJsonSchema as configJsonSchema, flow_destinationReferenceJsonSchema as destinationReferenceJsonSchema, flow_parseConfig as parseConfig, flow_parseSetup as parseSetup, flow_safeParseConfig as safeParseConfig, flow_safeParseSetup as safeParseSetup, flow_setupJsonSchema as setupJsonSchema, flow_sourceReferenceJsonSchema as sourceReferenceJsonSchema };
 }
 
 /**