@flow-conductor/adapter-node-fetch 1.0.0

package/README.md

@@ -0,0 +1,466 @@
+# @flow-conductor/adapter-node-fetch
+
+node-fetch adapter for flow-conductor. This adapter uses node-fetch, making it ideal for Node.js environments where you need a reliable HTTP client.
+
+## Installation
+
+```bash
+npm install @flow-conductor/adapter-node-fetch @flow-conductor/core node-fetch
+```
+
+**Note**: `@flow-conductor/core` and `node-fetch` are peer dependencies and must be installed alongside this package.
+
+## Quick Start
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { NodeFetchRequestAdapter } from "@flow-conductor/adapter-node-fetch";
+
+const adapter = new NodeFetchRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+const data = await result.json();
+console.log(data);
+```
+
+## Usage
+
+### Basic GET Request
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { NodeFetchRequestAdapter } from "@flow-conductor/adapter-node-fetch";
+
+const adapter = new NodeFetchRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+const user = await result.json();
+console.log(user);
+```
+
+### POST Request with Data
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { NodeFetchRequestAdapter } from "@flow-conductor/adapter-node-fetch";
+
+const adapter = new NodeFetchRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "POST",
+      data: {
+        name: "John Doe",
+        email: "john@example.com",
+      },
+    },
+  },
+  adapter
+).execute();
+
+const newUser = await result.json();
+console.log(newUser);
+```
+
+### Request with Custom Headers
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { NodeFetchRequestAdapter } from "@flow-conductor/adapter-node-fetch";
+
+const adapter = new NodeFetchRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+      headers: {
+        Authorization: "Bearer your-token-here",
+        "X-Custom-Header": "value",
+      },
+    },
+  },
+  adapter
+).execute();
+```
+
+### Chained Requests
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { NodeFetchRequestAdapter } from "@flow-conductor/adapter-node-fetch";
+
+const adapter = new NodeFetchRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "GET",
+    },
+  },
+  adapter
+)
+  .next({
+    config: async (previousResult) => {
+      const user = await previousResult.json();
+      return {
+        url: `https://api.example.com/users/${user.id}/posts`,
+        method: "GET",
+      };
+    },
+  })
+  .execute();
+
+const posts = await result.json();
+console.log(posts);
+```
+
+## Configuration
+
+The `NodeFetchRequestAdapter` accepts standard `IRequestConfig` objects compatible with node-fetch. The adapter automatically:
+
+- JSON stringifies `data` for non-GET requests
+- Sets `Content-Type: application/json` header when data is provided
+- Passes through all other node-fetch options
+
+### Request Config Interface
+
+```typescript
+interface NodeFetchRequestConfig extends IRequestConfig {
+  url: string;
+  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+  data?: any; // Will be JSON stringified for non-GET requests
+  headers?: Record<string, string>;
+  // ... other fetch options (redirect, timeout, etc.)
+}
+```
+
+### Supported Fetch Options
+
+All standard node-fetch options are supported:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+      headers: {
+        "Authorization": "Bearer token",
+      },
+      redirect: "follow", // Redirect handling
+      timeout: 5000, // Request timeout
+      // ... any other RequestInit options
+    },
+  },
+  adapter
+).execute();
+```
+
+### Data Handling
+
+The adapter automatically handles data serialization:
+
+- **GET requests**: Data is ignored (use query parameters in URL instead)
+- **Other methods**: Data is JSON stringified and sent as the request body
+- **Content-Type**: Automatically set to `application/json` when data is provided
+- **String data**: Passed through as-is
+- **Buffer/Uint8Array**: Passed through as binary data
+
+```typescript
+// POST with JSON data
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "POST",
+      data: { name: "John", email: "john@example.com" },
+      // Content-Type: application/json is automatically added
+    },
+  },
+  adapter
+).execute();
+
+// POST with string data
+const textResult = await begin(
+  {
+    config: {
+      url: "https://api.example.com/data",
+      method: "POST",
+      data: "raw string data",
+      // Content-Type will not be automatically set for string data
+    },
+  },
+  adapter
+).execute();
+
+// PUT with JSON data
+const updateResult = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "PUT",
+      data: { name: "Jane" },
+    },
+  },
+  adapter
+).execute();
+```
+
+### Custom Headers
+
+You can provide custom headers, which will be merged with default headers:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "POST",
+      data: { name: "John" },
+      headers: {
+        "Authorization": "Bearer token",
+        "X-Custom-Header": "value",
+        // Content-Type will be automatically added if not specified
+      },
+    },
+  },
+  adapter
+).execute();
+```
+
+## Response Handling
+
+The adapter returns a standard `Response` object from node-fetch. You can use all standard Response methods:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+// Standard Response methods
+const json = await result.json();
+const text = await result.text();
+const blob = await result.blob();
+const arrayBuffer = await result.arrayBuffer();
+
+// Response properties
+console.log(result.status); // HTTP status code
+console.log(result.statusText); // Status text
+console.log(result.ok); // true if status 200-299
+console.log(result.headers); // Headers object
+```
+
+## Error Handling
+
+node-fetch throws errors for network failures and rejects on HTTP error statuses (depending on configuration). You can handle errors using flow-conductor's error handling:
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { NodeFetchRequestAdapter } from "@flow-conductor/adapter-node-fetch";
+
+const adapter = new NodeFetchRequestAdapter();
+
+try {
+  const result = await begin(
+    {
+      config: {
+        url: "https://api.example.com/users",
+        method: "GET",
+      },
+    },
+    adapter
+  )
+    .withErrorHandler((error) => {
+      console.error("Request failed:", error);
+    })
+    .execute();
+
+  if (!result.ok) {
+    throw new Error(`HTTP error! status: ${result.status}`);
+  }
+
+  const data = await result.json();
+  console.log(data);
+} catch (error) {
+  console.error("Error:", error);
+}
+```
+
+## Node.js Environment
+
+This adapter is specifically designed for Node.js environments and uses `node-fetch` v3, which is ESM-only. Make sure your project is configured for ESM:
+
+```json
+{
+  "type": "module"
+}
+```
+
+### Requirements
+
+- Node.js 18+ (for native ESM support)
+- node-fetch v3.x
+
+## Examples
+
+### Authentication Flow
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { NodeFetchRequestAdapter } from "@flow-conductor/adapter-node-fetch";
+
+const adapter = new NodeFetchRequestAdapter();
+
+// Login and use token
+const userData = await begin(
+  {
+    config: {
+      url: "https://api.example.com/auth/login",
+      method: "POST",
+      data: { username: "user", password: "pass" },
+    },
+  },
+  adapter
+)
+  .next({
+    config: async (previousResult) => {
+      const auth = await previousResult.json();
+      return {
+        url: "https://api.example.com/user/profile",
+        method: "GET",
+        headers: { Authorization: `Bearer ${auth.token}` },
+      };
+    },
+  })
+  .execute();
+
+const profile = await userData.json();
+console.log(profile);
+```
+
+### File Upload
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { NodeFetchRequestAdapter } from "@flow-conductor/adapter-node-fetch";
+import { readFileSync } from "fs";
+
+const adapter = new NodeFetchRequestAdapter();
+
+// Upload file as Buffer
+const fileBuffer = readFileSync("./file.pdf");
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/upload",
+      method: "POST",
+      data: fileBuffer,
+      headers: {
+        "Content-Type": "application/pdf",
+      },
+    },
+  },
+  adapter
+).execute();
+```
+
+### Request with Timeout
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { NodeFetchRequestAdapter } from "@flow-conductor/adapter-node-fetch";
+
+const adapter = new NodeFetchRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+      timeout: 5000, // 5 second timeout
+    },
+  },
+  adapter
+).execute();
+```
+
+## API Reference
+
+### NodeFetchRequestAdapter
+
+```typescript
+class NodeFetchRequestAdapter extends RequestAdapter<Response, NodeFetchRequestConfig> {
+  createRequest(requestConfig: IRequestConfig): Promise<Response>;
+}
+```
+
+### NodeFetchRequestConfig
+
+```typescript
+type NodeFetchRequestConfig = IRequestConfig;
+```
+
+Extends `IRequestConfig` with all standard node-fetch options.
+
+## Differences from Native Fetch Adapter
+
+The `@flow-conductor/adapter-node-fetch` adapter is similar to `@flow-conductor/adapter-fetch`, but:
+
+- **Node.js only**: Designed specifically for Node.js environments
+- **node-fetch dependency**: Uses the `node-fetch` package instead of native fetch
+- **Better Node.js support**: May have better support for Node.js-specific features
+- **Consistent API**: Provides a consistent API across different Node.js versions
+
+Choose `@flow-conductor/adapter-node-fetch` if:
+- You're building a Node.js-only application
+- You need features specific to node-fetch
+- You want explicit control over the fetch implementation
+
+Choose `@flow-conductor/adapter-fetch` if:
+- You want to use the native Fetch API (Node.js 18+)
+- You want to avoid additional dependencies
+- You're building for both browser and Node.js
+
+## Requirements
+
+- `@flow-conductor/core` (peer dependency)
+- `node-fetch` v3.x (peer dependency)
+- Node.js 18+ (for native ESM support)
+- TypeScript 5.0+
+
+## License
+
+MIT
+
+
+

package/build/index.d.ts

@@ -0,0 +1,39 @@
+import { RequestAdapter, IRequestConfig, UrlValidationOptions } from '@flow-conductor/core';
+import { Response } from 'node-fetch';
+
+/**
+ * Request configuration type for node-fetch adapter.
+ * Extends IRequestConfig with node-fetch-specific options via the index signature.
+ */
+type NodeFetchRequestConfig = IRequestConfig;
+/**
+ * Request adapter implementation using node-fetch.
+ * Provides a Node.js-specific HTTP client adapter that works in Node.js environments.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new NodeFetchRequestAdapter();
+ * const chain = begin(
+ *   { config: { url: 'https://api.example.com/users', method: 'GET' } },
+ *   adapter
+ * );
+ * ```
+ */
+declare class NodeFetchRequestAdapter extends RequestAdapter<Response, NodeFetchRequestConfig> {
+    /**
+     * Creates a new NodeFetchRequestAdapter instance.
+     *
+     * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks
+     */
+    constructor(urlValidationOptions?: UrlValidationOptions);
+    /**
+     * Creates and executes an HTTP request using node-fetch.
+     * Automatically handles JSON serialization for request bodies.
+     *
+     * @param requestConfig - The request configuration object
+     * @returns A promise that resolves to a Response object
+     */
+    createRequest(requestConfig: IRequestConfig): Promise<Response>;
+}
+
+export { type NodeFetchRequestConfig, NodeFetchRequestAdapter as default };

package/build/index.js

@@ -0,0 +1,56 @@
+import { RequestAdapter } from '@flow-conductor/core';
+import fetch from 'node-fetch';
+
+// src/node-fetch-request-adapter.ts
+var NodeFetchRequestAdapter = class extends RequestAdapter {
+  /**
+   * Creates a new NodeFetchRequestAdapter instance.
+   *
+   * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks
+   */
+  constructor(urlValidationOptions) {
+    super(urlValidationOptions);
+  }
+  /**
+   * Creates and executes an HTTP request using node-fetch.
+   * Automatically handles JSON serialization for request bodies.
+   *
+   * @param requestConfig - The request configuration object
+   * @returns A promise that resolves to a Response object
+   */
+  async createRequest(requestConfig) {
+    const { data, url, method, headers, ...rest } = requestConfig;
+    const fetchConfig = {
+      method,
+      ...rest
+    };
+    const headersObj = headers ? { ...headers } : {};
+    if (data !== void 0) {
+      if (data === null) {
+        fetchConfig.body = JSON.stringify(null);
+        if (!headersObj["Content-Type"] && !headersObj["content-type"]) {
+          headersObj["Content-Type"] = "application/json";
+        }
+      } else if (typeof data === "string") {
+        fetchConfig.body = data;
+      } else if (data instanceof Buffer) {
+        fetchConfig.body = data;
+      } else if (data instanceof Uint8Array) {
+        fetchConfig.body = Buffer.from(data);
+      } else {
+        fetchConfig.body = JSON.stringify(data);
+        if (!headersObj["Content-Type"] && !headersObj["content-type"]) {
+          headersObj["Content-Type"] = "application/json";
+        }
+      }
+    }
+    if (Object.keys(headersObj).length > 0) {
+      fetchConfig.headers = headersObj;
+    }
+    return fetch(url, fetchConfig);
+  }
+};
+
+export { NodeFetchRequestAdapter as default };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/node-fetch-request-adapter.ts"],"names":[],"mappings":";;;;AA2BA,IAAqB,uBAAA,GAArB,cAAqD,cAAA,CAGnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,YAAY,oBAAA,EAA6C;AACvD,IAAA,KAAA,CAAM,oBAAoB,CAAA;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAa,cAAc,aAAA,EAAkD;AAC3E,IAAA,MAAM,EAAE,IAAA,EAAM,GAAA,EAAK,QAAQ,OAAA,EAAS,GAAG,MAAK,GAAI,aAAA;AAChD,IAAA,MAAM,WAAA,GAA2B;AAAA,MAC/B,MAAA;AAAA,MACA,GAAG;AAAA,KACL;AAGA,IAAA,MAAM,aAAqC,OAAA,GACvC,EAAE,GAAI,OAAA,KACN,EAAC;AAGL,IAAA,IAAI,SAAS,MAAA,EAAW;AACtB,MAAA,IAAI,SAAS,IAAA,EAAM;AACjB,QAAA,WAAA,CAAY,IAAA,GAAO,IAAA,CAAK,SAAA,CAAU,IAAI,CAAA;AAEtC,QAAA,IAAI,CAAC,UAAA,CAAW,cAAc,KAAK,CAAC,UAAA,CAAW,cAAc,CAAA,EAAG;AAC9D,UAAA,UAAA,CAAW,cAAc,CAAA,GAAI,kBAAA;AAAA,QAC/B;AAAA,MACF,CAAA,MAAA,IAAW,OAAO,IAAA,KAAS,QAAA,EAAU;AACnC,QAAA,WAAA,CAAY,IAAA,GAAO,IAAA;AAAA,MACrB,CAAA,MAAA,IAAW,gBAAgB,MAAA,EAAQ;AACjC,QAAA,WAAA,CAAY,IAAA,GAAO,IAAA;AAAA,MACrB,CAAA,MAAA,IAAW,gBAAgB,UAAA,EAAY;AACrC,QAAA,WAAA,CAAY,IAAA,GAAO,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA;AAAA,MACrC,CAAA,MAAO;AACL,QAAA,WAAA,CAAY,IAAA,GAAO,IAAA,CAAK,SAAA,CAAU,IAAI,CAAA;AAEtC,QAAA,IAAI,CAAC,UAAA,CAAW,cAAc,KAAK,CAAC,UAAA,CAAW,cAAc,CAAA,EAAG;AAC9D,UAAA,UAAA,CAAW,cAAc,CAAA,GAAI,kBAAA;AAAA,QAC/B;AAAA,MACF;AAAA,IACF;AAGA,IAAA,IAAI,MAAA,CAAO,IAAA,CAAK,UAAU,CAAA,CAAE,SAAS,CAAA,EAAG;AACtC,MAAA,WAAA,CAAY,OAAA,GAAU,UAAA;AAAA,IACxB;AAEA,IAAA,OAAO,KAAA,CAAM,KAAK,WAAW,CAAA;AAAA,EAC/B;AACF","file":"index.js","sourcesContent":["import { RequestAdapter } from \"@flow-conductor/core\";\nimport type {\n  IRequestConfig,\n  UrlValidationOptions,\n} from \"@flow-conductor/core\";\nimport fetch from \"node-fetch\";\nimport type { RequestInit, Response } from \"node-fetch\";\n\n/**\n * Request configuration type for node-fetch adapter.\n * Extends IRequestConfig with node-fetch-specific options via the index signature.\n */\nexport type NodeFetchRequestConfig = IRequestConfig;\n\n/**\n * Request adapter implementation using node-fetch.\n * Provides a Node.js-specific HTTP client adapter that works in Node.js environments.\n *\n * @example\n * ```typescript\n * const adapter = new NodeFetchRequestAdapter();\n * const chain = begin(\n *   { config: { url: 'https://api.example.com/users', method: 'GET' } },\n *   adapter\n * );\n * ```\n */\nexport default class NodeFetchRequestAdapter extends RequestAdapter<\n  Response,\n  NodeFetchRequestConfig\n> {\n  /**\n   * Creates a new NodeFetchRequestAdapter instance.\n   *\n   * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks\n   */\n  constructor(urlValidationOptions?: UrlValidationOptions) {\n    super(urlValidationOptions);\n  }\n\n  /**\n   * Creates and executes an HTTP request using node-fetch.\n   * Automatically handles JSON serialization for request bodies.\n   *\n   * @param requestConfig - The request configuration object\n   * @returns A promise that resolves to a Response object\n   */\n  public async createRequest(requestConfig: IRequestConfig): Promise<Response> {\n    const { data, url, method, headers, ...rest } = requestConfig;\n    const fetchConfig: RequestInit = {\n      method,\n      ...rest,\n    };\n\n    // Handle headers - merge with existing headers if any\n    const headersObj: Record<string, string> = headers\n      ? { ...(headers as Record<string, string>) }\n      : {};\n\n    // Handle request body\n    if (data !== undefined) {\n      if (data === null) {\n        fetchConfig.body = JSON.stringify(null);\n        // Set Content-Type header if not already set\n        if (!headersObj[\"Content-Type\"] && !headersObj[\"content-type\"]) {\n          headersObj[\"Content-Type\"] = \"application/json\";\n        }\n      } else if (typeof data === \"string\") {\n        fetchConfig.body = data;\n      } else if (data instanceof Buffer) {\n        fetchConfig.body = data;\n      } else if (data instanceof Uint8Array) {\n        fetchConfig.body = Buffer.from(data);\n      } else {\n        fetchConfig.body = JSON.stringify(data);\n        // Set Content-Type header if not already set\n        if (!headersObj[\"Content-Type\"] && !headersObj[\"content-type\"]) {\n          headersObj[\"Content-Type\"] = \"application/json\";\n        }\n      }\n    }\n\n    // Set headers if we have any\n    if (Object.keys(headersObj).length > 0) {\n      fetchConfig.headers = headersObj;\n    }\n\n    return fetch(url, fetchConfig);\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@flow-conductor/adapter-node-fetch",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "node-fetch adapter for flow-conductor",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js"
+    }
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "build/**/*.js.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "flow-conductor",
+    "request",
+    "adapter",
+    "node-fetch",
+    "http",
+    "typescript"
+  ],
+  "scripts": {
+    "test": "node --test --import tsx/esm 'src/__test__/**/*.test.ts'",
+    "test:watch": "node --test --import tsx/esm --watch 'src/__test__/**/*.test.ts'",
+    "build": "tsup",
+    "clean": "rm -rf build",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run lint && npm run type-check && npm run build"
+  },
+  "author": "Dawid Hermann",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dawidhermann/flow-conductor.git",
+    "directory": "packages/adapter-node-fetch"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@flow-conductor/core": "^1.0.0",
+    "node-fetch": "^3.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@flow-conductor/core": "*",
+    "@types/node-fetch": "^2.6.11",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "node-fetch": "^3.3.2",
+    "prettier": "^3.7.4",
+    "tsx": "^4.7.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1"
+  }
+}