Merge pull request #573 from elbwalker/542-server-api-destination

542 server api destination

Author: alexanderkirtzel

package-lock.json

@@ -23,8 +23,10 @@
     "website"
   ],
   "scripts": {
-    "build": "turbo run build --filter=!@walkeros/website --output-logs=errors-only",
-    "build:website": "turbo run build --filter=@walkeros/website  --output-logs=errors-only",
+    "build": "npm run build:packages && npm run build:apps && npm run build:website",
+    "build:packages": "turbo run build --filter='./packages/**'",
+    "build:apps": "turbo run build --filter='./apps/*'",
+    "build:website": "turbo run build --filter=@walkeros/website",
     "clean": "turbo run clean",
     "dev": "turbo run dev --output-logs=errors-only",
     "format": "prettier --write .",

package.json

@@ -0,0 +1,158 @@
+<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>
+
+# API Destination for walkerOS
+
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/api)
+&bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/server-destination-api)
+
+walkerOS follows a **source → collector → destination** architecture. This API
+destination receives processed events from the walkerOS collector and sends them
+to any HTTP(S) endpoint, enabling integration with custom APIs, webhooks, and
+third-party services.
+
+## Installation
+
+```sh
+npm install @walkeros/server-destination-api
+```
+
+## Quick Start
+
+Configure in your Flow JSON:
+
+```json
+{
+  "version": 1,
+  "flows": {
+    "default": {
+      "server": {},
+      "destinations": {
+        "api": {
+          "package": "@walkeros/server-destination-api",
+          "config": {
+            "settings": {
+              "url": "https://api.example.com/events"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Or programmatically:
+
+```typescript
+import { startFlow } from '@walkeros/collector';
+import { destinationAPI } from '@walkeros/server-destination-api';
+
+const { elb } = await startFlow({
+  destinations: [
+    {
+      destination: destinationAPI,
+      config: {
+        settings: {
+          url: 'https://api.example.com/events',
+          headers: {
+            Authorization: 'Bearer your-api-key',
+            'Content-Type': 'application/json',
+          },
+          method: 'POST',
+          timeout: 5000,
+        },
+      },
+    },
+  ],
+});
+```
+
+## Configuration
+
+| Name        | Type                     | Description                         | Required | Default |
+| ----------- | ------------------------ | ----------------------------------- | -------- | ------- |
+| `url`       | `string`                 | The API endpoint URL to send events | Yes      | -       |
+| `headers`   | `Record<string, string>` | Custom HTTP headers                 | No       | -       |
+| `method`    | `string`                 | HTTP method                         | No       | `POST`  |
+| `timeout`   | `number`                 | Request timeout in milliseconds     | No       | `5000`  |
+| `transform` | `Function`               | Custom data transformation function | No       | -       |
+
+## Features
+
+- **Flexible URL Configuration**: Send events to any HTTP(S) endpoint
+- **Custom Headers**: Add authentication tokens, API keys, or custom headers
+- **HTTP Method Control**: Use POST, PUT, PATCH, or any HTTP method
+- **Request Timeout**: Configure timeout for slow endpoints
+- **Data Transformation**: Transform event data before sending with custom
+  functions
+- **Dependency Injection**: Mock the sendServer function for testing
+
+## Advanced Usage
+
+### Custom Transform Function
+
+Transform event data before sending:
+
+```typescript
+import { destinationAPI } from '@walkeros/server-destination-api';
+
+const config = {
+  settings: {
+    url: 'https://api.example.com/events',
+    transform: (data, config, mapping) => {
+      // Return custom body (string or object)
+      return JSON.stringify({
+        eventType: data.event,
+        properties: data.data,
+        timestamp: Date.now(),
+      });
+    },
+  },
+};
+```
+
+### Using with Mapping
+
+Use walkerOS mapping to transform events:
+
+```typescript
+const config = {
+  settings: { url: 'https://api.example.com/events' },
+  mapping: {
+    page: {
+      view: {
+        data: {
+          map: {
+            pageUrl: 'data.path',
+            pageTitle: 'data.title',
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+## Type Definitions
+
+See [src/types/](./src/types/) for TypeScript interfaces.
+
+## Related
+
+- [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.

packages/server/destinations/api/README.md

@@ -0,0 +1,5 @@
+import baseConfig from '@walkeros/config/jest';
+
+const config = {};
+
+export default { ...baseConfig, ...config };

packages/server/destinations/api/jest.config.mjs

@@ -0,0 +1,64 @@
+{
+  "name": "@walkeros/server-destination-api",
+  "description": "API server destination for walkerOS",
+  "version": "0.5.0",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./dev": {
+      "types": "./dist/dev.d.ts",
+      "import": "./dist/dev.mjs",
+      "require": "./dist/dev.js"
+    },
+    "./examples": {
+      "types": "./dist/examples/index.d.ts",
+      "import": "./dist/examples/index.mjs",
+      "require": "./dist/examples/index.js"
+    }
+  },
+  "files": [
+    "dist/**"
+  ],
+  "scripts": {
+    "build": "tsup --silent",
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "dev": "jest --watchAll --colors",
+    "lint": "tsc && eslint \"**/*.ts*\"",
+    "test": "jest",
+    "update": "npx npm-check-updates -u && npm update"
+  },
+  "dependencies": {
+    "@walkeros/core": "0.5.0",
+    "@walkeros/server-core": "0.5.0"
+  },
+  "devDependencies": {},
+  "repository": {
+    "url": "git+https://github.com/elbwalker/walkerOS.git",
+    "directory": "packages/server/destinations/api"
+  },
+  "author": "elbwalker <[email protected]>",
+  "homepage": "https://github.com/elbwalker/walkerOS#readme",
+  "bugs": {
+    "url": "https://github.com/elbwalker/walkerOS/issues"
+  },
+  "keywords": [
+    "walker",
+    "walkerOS",
+    "destination",
+    "server",
+    "api"
+  ],
+  "funding": [
+    {
+      "type": "GitHub Sponsors",
+      "url": "https://github.com/sponsors/elbwalker"
+    }
+  ]
+}

packages/server/destinations/api/package.json

@@ -0,0 +1,2 @@
+export * as schemas from './schemas';
+export * as examples from './examples';

packages/server/destinations/api/src/dev.ts

@@ -0,0 +1,20 @@
+import type { Env } from '../types';
+
+/**
+ * Example environment configurations for API destination
+ *
+ * These environments provide standardized mock structures for testing
+ * and development without requiring external dependencies.
+ */
+
+const noop = () => Promise.resolve({ ok: true });
+
+export const init: Env | undefined = {
+  sendServer: undefined,
+};
+
+export const standard: Env = {
+  sendServer: Object.assign(noop, {
+    // Add any specific properties if needed for sendServer
+  }) as unknown as Env['sendServer'],
+};

packages/server/destinations/api/src/examples/env.ts

@@ -0,0 +1,7 @@
+import { getEvent } from '@walkeros/core';
+
+export function entity_action() {
+  const event = getEvent('entity action');
+
+  return JSON.stringify(event.data);
+}

packages/server/destinations/api/src/examples/events.ts

@@ -0,0 +1,4 @@
+export * as env from './env';
+export * as events from './events';
+export * as mapping from './mapping';
+export * as outputs from './outputs';

packages/server/destinations/api/src/examples/index.ts

@@ -0,0 +1,10 @@
+import type { Mapping } from '@walkeros/core';
+import type { Rule, Rules } from '../types';
+
+export const entity_action: Rule = {
+  data: 'data',
+};
+
+export const config = {
+  entity: { action: entity_action },
+} satisfies Rules;