@flow-conductor/adapter-fetch 1.0.0

package/README.md

@@ -0,0 +1,422 @@
+# @flow-conductor/adapter-fetch
+
+Fetch API adapter for flow-conductor. This adapter uses the native Fetch API available in Node.js 18+ and modern browsers.
+
+## Installation
+
+```bash
+npm install @flow-conductor/adapter-fetch @flow-conductor/core
+```
+
+**Note**: `@flow-conductor/core` is a peer dependency and must be installed alongside this package.
+
+## Quick Start
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+
+const adapter = new FetchRequestAdapter();
+
+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 { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+
+const adapter = new FetchRequestAdapter();
+
+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 { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+
+const adapter = new FetchRequestAdapter();
+
+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 { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+
+const adapter = new FetchRequestAdapter();
+
+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 { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+
+const adapter = new FetchRequestAdapter();
+
+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 `FetchRequestAdapter` accepts standard `IRequestConfig` objects compatible with the Fetch API. The adapter automatically:
+
+- JSON stringifies `data` for non-GET requests
+- Sets `Content-Type: application/json` header when data is provided
+- Passes through all other Fetch API options
+
+### Request Config Interface
+
+```typescript
+interface FetchRequestConfig 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 (credentials, cache, mode, etc.)
+}
+```
+
+### Supported Fetch Options
+
+All standard Fetch API options are supported:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+      headers: {
+        "Authorization": "Bearer token",
+      },
+      credentials: "include", // Include cookies
+      cache: "no-cache", // Cache control
+      mode: "cors", // CORS mode
+      redirect: "follow", // Redirect handling
+      // ... 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
+
+```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();
+
+// 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 the Fetch API. 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
+
+The Fetch API only rejects on network errors, not HTTP error statuses. You may want to check the response status:
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+
+const adapter = new FetchRequestAdapter();
+
+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);
+}
+```
+
+## Browser vs Node.js
+
+### Browser
+
+The Fetch API is natively available in modern browsers. No additional setup needed.
+
+```typescript
+// Works in browsers with native fetch support
+import { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+const adapter = new FetchRequestAdapter();
+```
+
+### Node.js
+
+Node.js 18+ includes native Fetch API support. For older versions, you may need a polyfill:
+
+```typescript
+// Node.js 18+
+import { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+const adapter = new FetchRequestAdapter();
+
+// Node.js < 18 (requires polyfill)
+import fetch from "node-fetch";
+import { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+
+// Note: You may need to configure the adapter to use the polyfill
+// or use a different adapter implementation
+```
+
+## Examples
+
+### Authentication Flow
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+
+const adapter = new FetchRequestAdapter();
+
+// 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 { FetchRequestAdapter } from "@flow-conductor/adapter-fetch";
+
+const adapter = new FetchRequestAdapter();
+
+// Note: For file uploads, you may need to customize the adapter
+// to handle FormData instead of JSON
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/upload",
+      method: "POST",
+      data: formData, // FormData object
+      headers: {
+        // Don't set Content-Type, let browser set it with boundary
+      },
+    },
+  },
+  adapter
+).execute();
+```
+
+## API Reference
+
+### FetchRequestAdapter
+
+```typescript
+class FetchRequestAdapter extends RequestAdapter<Response, FetchRequestConfig> {
+  createRequest(requestConfig: IRequestConfig): Promise<Response>;
+}
+```
+
+### FetchRequestConfig
+
+```typescript
+type FetchRequestConfig = IRequestConfig;
+```
+
+Extends `IRequestConfig` with all standard Fetch API options.
+
+## Requirements
+
+- `@flow-conductor/core` (peer dependency)
+- Node.js 18+ (for native Fetch API) or a Fetch polyfill
+- TypeScript 5.0+
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,38 @@
+import { RequestAdapter, IRequestConfig, UrlValidationOptions } from '@flow-conductor/core';
+
+/**
+ * Request configuration type for Fetch adapter.
+ * Extends IRequestConfig with fetch-specific options via the index signature.
+ */
+type FetchRequestConfig = IRequestConfig;
+/**
+ * Request adapter implementation using the native Fetch API.
+ * Provides a lightweight, dependency-free HTTP client adapter.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new FetchRequestAdapter();
+ * const chain = begin(
+ *   { config: { url: 'https://api.example.com/users', method: 'GET' } },
+ *   adapter
+ * );
+ * ```
+ */
+declare class FetchRequestAdapter extends RequestAdapter<Response, FetchRequestConfig> {
+    /**
+     * Creates a new FetchRequestAdapter instance.
+     *
+     * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks
+     */
+    constructor(urlValidationOptions?: UrlValidationOptions);
+    /**
+     * Creates and executes an HTTP request using the Fetch API.
+     * 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 FetchRequestConfig, FetchRequestAdapter as default };

package/build/index.js

@@ -0,0 +1,36 @@
+import { RequestAdapter } from '@flow-conductor/core';
+
+// src/fetch-request-adapter.ts
+var FetchRequestAdapter = class extends RequestAdapter {
+  /**
+   * Creates a new FetchRequestAdapter instance.
+   *
+   * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks
+   */
+  constructor(urlValidationOptions) {
+    super(urlValidationOptions);
+  }
+  /**
+   * Creates and executes an HTTP request using the Fetch API.
+   * Automatically handles JSON serialization for request bodies.
+   *
+   * @param requestConfig - The request configuration object
+   * @returns A promise that resolves to a Response object
+   */
+  createRequest(requestConfig) {
+    const { data, url, ...rest } = requestConfig;
+    const fetchConfig = { ...rest };
+    if (data) {
+      fetchConfig.body = typeof data === "string" ? data : JSON.stringify(data);
+      fetchConfig.headers = {
+        "Content-Type": "application/json",
+        ...fetchConfig.headers
+      };
+    }
+    return fetch(url, fetchConfig);
+  }
+};
+
+export { FetchRequestAdapter as default };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fetch-request-adapter.ts"],"names":[],"mappings":";;;AAyBA,IAAqB,mBAAA,GAArB,cAAiD,cAAA,CAG/C;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,EASO,cAAc,aAAA,EAAkD;AACrE,IAAA,MAAM,EAAE,IAAA,EAAM,GAAA,EAAK,GAAG,MAAK,GAAI,aAAA;AAC/B,IAAA,MAAM,WAAA,GAA2B,EAAE,GAAG,IAAA,EAAK;AAC3C,IAAA,IAAI,IAAA,EAAM;AACR,MAAA,WAAA,CAAY,OAAO,OAAO,IAAA,KAAS,WAAW,IAAA,GAAO,IAAA,CAAK,UAAU,IAAI,CAAA;AACxE,MAAA,WAAA,CAAY,OAAA,GAAU;AAAA,QACpB,cAAA,EAAgB,kBAAA;AAAA,QAChB,GAAI,WAAA,CAAY;AAAA,OAClB;AAAA,IACF;AACA,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\";\n\n/**\n * Request configuration type for Fetch adapter.\n * Extends IRequestConfig with fetch-specific options via the index signature.\n */\nexport type FetchRequestConfig = IRequestConfig;\n\n/**\n * Request adapter implementation using the native Fetch API.\n * Provides a lightweight, dependency-free HTTP client adapter.\n *\n * @example\n * ```typescript\n * const adapter = new FetchRequestAdapter();\n * const chain = begin(\n *   { config: { url: 'https://api.example.com/users', method: 'GET' } },\n *   adapter\n * );\n * ```\n */\nexport default class FetchRequestAdapter extends RequestAdapter<\n  Response,\n  FetchRequestConfig\n> {\n  /**\n   * Creates a new FetchRequestAdapter 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 the Fetch API.\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 createRequest(requestConfig: IRequestConfig): Promise<Response> {\n    const { data, url, ...rest } = requestConfig;\n    const fetchConfig: RequestInit = { ...rest };\n    if (data) {\n      fetchConfig.body = typeof data === \"string\" ? data : JSON.stringify(data);\n      fetchConfig.headers = {\n        \"Content-Type\": \"application/json\",\n        ...(fetchConfig.headers as Record<string, string>),\n      };\n    }\n    return fetch(url, fetchConfig);\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@flow-conductor/adapter-fetch",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Fetch API 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",
+    "fetch",
+    "http",
+    "typescript"
+  ],
+  "scripts": {
+    "test": "echo \"No tests specified\" && exit 0",
+    "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-fetch"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@flow-conductor/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@flow-conductor/core": "*",
+    "@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",
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1"
+  }
+}