@walkeros/web-destination-api 0.0.0-next-20251219153324

package/README.md

@@ -0,0 +1,209 @@
+<p align="left">
+  <a href="https://www.walkeros.io">
+    <img title="elbwalker" src="https://www.walkeros.io/img/elbwalker_logo.png" width="256px"/>
+  </a>
+</p>
+
+# Web API Destination for walkerOS
+
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/api)
+&bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-api)
+
+The API destination allows you to send events to any HTTP endpoint with
+customizable data transformation and transport methods.
+
+walkerOS follows a **source → collector → destination** architecture. This API
+destination receives processed events from the walkerOS collector and sends them
+to your custom API endpoint, enabling integration with internal analytics
+systems, data warehouses, or custom business logic that requires real-time event
+data.
+
+## Installation
+
+```sh
+npm install @walkeros/web-destination-api
+```
+
+## Configuration
+
+| Name        | Type                           | Description                                      | Required | Example                                                                   |
+| ----------- | ------------------------------ | ------------------------------------------------ | -------- | ------------------------------------------------------------------------- |
+| `url`       | `string`                       | The HTTP endpoint URL to send events to          | Yes      | `'https://api.example.com/events'`                                        |
+| `headers`   | `Record<string, string>`       | Additional HTTP headers to include with requests | No       | `{ 'Authorization': 'Bearer token', 'Content-Type': 'application/json' }` |
+| `method`    | `string`                       | HTTP method for the request                      | No       | `'POST'`                                                                  |
+| `transform` | `function`                     | Function to transform event data before sending  | No       | `(data, config, mapping) => JSON.stringify(data)`                         |
+| `transport` | `'fetch' \| 'xhr' \| 'beacon'` | Transport method for sending requests            | No       | `'fetch'`                                                                 |
+
+## Quick Start
+
+Configure in your Flow JSON:
+
+```json
+{
+  "version": 1,
+  "flows": {
+    "default": {
+      "web": {},
+      "destinations": {
+        "api": {
+          "package": "@walkeros/web-destination-api",
+          "config": {
+            "settings": {
+              "url": "https://api.example.com/events",
+              "method": "POST",
+              "headers": { "Authorization": "Bearer your-token" }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Or programmatically:
+
+```typescript
+import { startFlow } from '@walkeros/collector';
+import { destinationAPI } from '@walkeros/web-destination-api';
+
+const { elb } = await startFlow({
+  destinations: [
+    {
+      destination: destinationAPI,
+      config: {
+        settings: {
+          url: 'https://api.example.com/events',
+          method: 'POST',
+          headers: { Authorization: 'Bearer your-token' },
+        },
+      },
+    },
+  ],
+});
+```
+
+## Usage
+
+### Advanced Usage with Transform
+
+```typescript
+import { startFlow } from '@walkeros/collector';
+import { destinationAPI } from '@walkeros/web-destination-api';
+
+const { elb } = await startFlow({
+  destinations: [
+    {
+      destination: destinationAPI,
+      config: {
+        settings: {
+          url: 'https://api.example.com/events',
+          transport: 'fetch',
+          transform: (event, config, mapping) => {
+            return JSON.stringify({
+              timestamp: Date.now(),
+              event_name: `${event.entity}_${event.action}`,
+              properties: event.data,
+              context: event.context,
+            });
+          },
+        },
+      },
+    },
+  ],
+});
+```
+
+## Examples
+
+### Sending to Analytics API
+
+```json
+{
+  "destinations": {
+    "analytics": {
+      "package": "@walkeros/web-destination-api",
+      "config": {
+        "settings": {
+          "url": "https://analytics.example.com/track",
+          "method": "POST",
+          "headers": {
+            "Content-Type": "application/json",
+            "X-API-Key": "your-api-key"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Using Beacon Transport
+
+For critical events that need to be sent even when the page is unloading:
+
+```json
+{
+  "destinations": {
+    "critical": {
+      "package": "@walkeros/web-destination-api",
+      "config": {
+        "settings": {
+          "url": "https://api.example.com/critical-events",
+          "transport": "beacon"
+        }
+      }
+    }
+  }
+}
+```
+
+### Custom Data Mapping
+
+Use mapping rules to control which events are sent:
+
+```json
+{
+  "destinations": {
+    "api": {
+      "package": "@walkeros/web-destination-api",
+      "config": {
+        "settings": { "url": "https://api.example.com/events" },
+        "mapping": {
+          "entity": {
+            "action": { "data": "data" }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Transport Methods
+
+- **fetch** (default): Modern, promise-based HTTP requests
+- **xhr**: Traditional XMLHttpRequest for older browser compatibility
+- **beacon**: Uses Navigator.sendBeacon() for reliable data transmission during
+  page unload
+
+## Type Definitions
+
+See [src/types/](./src/types/) for TypeScript interfaces.
+
+## Related
+
+- [Website Documentation](https://www.walkeros.io/docs/destinations/web/api/)
+- [Destination Interface](../../../core/src/types/destination.ts)
+
+## Contribute
+
+Feel free to contribute by submitting an
+[issue](https://github.com/elbwalker/walkerOS/issues), starting a
+[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
+[contact](https://calendly.com/elb-alexander/30min).
+
+## License
+
+This project is licensed under the MIT License.

package/dist/dev.d.mts

@@ -0,0 +1,81 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Mapping as Mapping$2 } from '@walkeros/core';
+import { DestinationWeb, sendWeb } from '@walkeros/web-core';
+
+declare const SettingsSchema: z.ZodObject<{
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    method: z.ZodDefault<z.ZodString>;
+    transform: z.ZodOptional<z.ZodAny>;
+    transport: z.ZodDefault<z.ZodEnum<{
+        fetch: "fetch";
+        xhr: "xhr";
+        beacon: "beacon";
+    }>>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{}, z.core.$strip>;
+type Mapping$1 = z.infer<typeof MappingSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const mapping$1: _walkeros_core_dev.JSONSchema;
+
+declare const index$1_MappingSchema: typeof MappingSchema;
+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 Mapping$1 as Mapping, index$1_MappingSchema as MappingSchema, type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, mapping$1 as mapping, index$1_settings as settings };
+}
+
+interface Mapping {
+}
+interface Env extends DestinationWeb.Env {
+    sendWeb?: typeof sendWeb;
+}
+type Rule = Mapping$2.Rule<Mapping>;
+
+declare const init: Env | undefined;
+declare const push: Env;
+/**
+ * Simulation tracking paths
+ * Specifies which function calls to track during simulation
+ */
+declare const simulation: string[];
+
+declare const env_init: typeof init;
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_init as init, env_push as push, env_simulation as simulation };
+}
+
+declare function entity_action$1(): string;
+
+declare namespace events {
+  export { entity_action$1 as entity_action };
+}
+
+declare const entity_action: Rule;
+declare const config: {
+    entity: {
+        action: Rule;
+    };
+};
+
+declare const mapping_config: typeof config;
+declare const mapping_entity_action: typeof entity_action;
+declare namespace mapping {
+  export { mapping_config as config, mapping_entity_action as entity_action };
+}
+
+declare const index_env: typeof env;
+declare const index_events: typeof events;
+declare const index_mapping: typeof mapping;
+declare namespace index {
+  export { index_env as env, index_events as events, index_mapping as mapping };
+}
+
+export { index as examples, index$1 as schemas };

package/dist/dev.d.ts

@@ -0,0 +1,81 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Mapping as Mapping$2 } from '@walkeros/core';
+import { DestinationWeb, sendWeb } from '@walkeros/web-core';
+
+declare const SettingsSchema: z.ZodObject<{
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    method: z.ZodDefault<z.ZodString>;
+    transform: z.ZodOptional<z.ZodAny>;
+    transport: z.ZodDefault<z.ZodEnum<{
+        fetch: "fetch";
+        xhr: "xhr";
+        beacon: "beacon";
+    }>>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{}, z.core.$strip>;
+type Mapping$1 = z.infer<typeof MappingSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const mapping$1: _walkeros_core_dev.JSONSchema;
+
+declare const index$1_MappingSchema: typeof MappingSchema;
+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 Mapping$1 as Mapping, index$1_MappingSchema as MappingSchema, type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, mapping$1 as mapping, index$1_settings as settings };
+}
+
+interface Mapping {
+}
+interface Env extends DestinationWeb.Env {
+    sendWeb?: typeof sendWeb;
+}
+type Rule = Mapping$2.Rule<Mapping>;
+
+declare const init: Env | undefined;
+declare const push: Env;
+/**
+ * Simulation tracking paths
+ * Specifies which function calls to track during simulation
+ */
+declare const simulation: string[];
+
+declare const env_init: typeof init;
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_init as init, env_push as push, env_simulation as simulation };
+}
+
+declare function entity_action$1(): string;
+
+declare namespace events {
+  export { entity_action$1 as entity_action };
+}
+
+declare const entity_action: Rule;
+declare const config: {
+    entity: {
+        action: Rule;
+    };
+};
+
+declare const mapping_config: typeof config;
+declare const mapping_entity_action: typeof entity_action;
+declare namespace mapping {
+  export { mapping_config as config, mapping_entity_action as entity_action };
+}
+
+declare const index_env: typeof env;
+declare const index_events: typeof events;
+declare const index_mapping: typeof mapping;
+declare namespace index {
+  export { index_env as env, index_events as events, index_mapping as mapping };
+}
+
+export { index as examples, index$1 as schemas };