@flow-conductor/adapter-superagent 1.0.0

package/README.md

@@ -0,0 +1,464 @@
+# @flow-conductor/adapter-superagent
+
+Superagent adapter for flow-conductor. This adapter uses Superagent for making HTTP requests, providing a fluent API and excellent browser/Node.js support.
+
+## Installation
+
+```bash
+npm install @flow-conductor/adapter-superagent @flow-conductor/core superagent
+```
+
+**Note**: Both `@flow-conductor/core` and `superagent` are peer dependencies and must be installed alongside this package.
+
+## Quick Start
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { SuperagentRequestAdapter } from "@flow-conductor/adapter-superagent";
+
+const adapter = new SuperagentRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+console.log(result.body); // Response body
+console.log(result.status); // HTTP status code
+console.log(result.headers); // Response headers
+```
+
+## Usage
+
+### Basic GET Request
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { SuperagentRequestAdapter } from "@flow-conductor/adapter-superagent";
+
+const adapter = new SuperagentRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+const user = result.body; // Response body
+console.log(user);
+```
+
+### POST Request with Data
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { SuperagentRequestAdapter } from "@flow-conductor/adapter-superagent";
+
+const adapter = new SuperagentRequestAdapter();
+
+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 = result.body;
+console.log(newUser);
+```
+
+### Request with Custom Headers
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { SuperagentRequestAdapter } from "@flow-conductor/adapter-superagent";
+
+const adapter = new SuperagentRequestAdapter();
+
+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 { SuperagentRequestAdapter } from "@flow-conductor/adapter-superagent";
+
+const adapter = new SuperagentRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "GET",
+    },
+  },
+  adapter
+)
+  .next({
+    config: (previousResult) => {
+      const user = previousResult.body;
+      return {
+        url: `https://api.example.com/users/${user.id}/posts`,
+        method: "GET",
+      };
+    },
+  })
+  .execute();
+
+const posts = result.body;
+console.log(posts);
+```
+
+## Configuration
+
+The `SuperagentRequestAdapter` accepts `IRequestConfig` objects. The adapter automatically:
+
+- Handles request data serialization
+- Sets headers appropriately
+- Supports all HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
+
+### Request Config Interface
+
+```typescript
+interface SuperagentRequestConfig extends IRequestConfig {
+  url: string;
+  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+  data?: any; // Request body
+  headers?: Record<string, string>;
+}
+```
+
+### Supported HTTP Methods
+
+All standard HTTP methods are supported:
+
+```typescript
+// GET
+const getResult = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+// POST
+const postResult = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "POST",
+      data: { name: "John" },
+    },
+  },
+  adapter
+).execute();
+
+// PUT
+const putResult = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "PUT",
+      data: { name: "Jane" },
+    },
+  },
+  adapter
+).execute();
+
+// DELETE
+const deleteResult = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "DELETE",
+    },
+  },
+  adapter
+).execute();
+```
+
+### Data Handling
+
+Superagent automatically handles data serialization:
+
+- **Objects**: Automatically JSON stringified
+- **FormData**: Sent as multipart/form-data
+- **URLSearchParams**: Sent as application/x-www-form-urlencoded
+- **Strings**: Sent as-is
+
+```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 set
+    },
+  },
+  adapter
+).execute();
+
+// POST with FormData
+const formData = new FormData();
+formData.append("file", fileBlob);
+
+const uploadResult = await begin(
+  {
+    config: {
+      url: "https://api.example.com/upload",
+      method: "POST",
+      data: formData,
+      // Content-Type: multipart/form-data is automatically set
+    },
+  },
+  adapter
+).execute();
+```
+
+## Response Handling
+
+The adapter returns a Superagent `Response` object with the following properties:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+// Response properties
+console.log(result.body); // Response body (automatically parsed JSON)
+console.log(result.text); // Response text
+console.log(result.status); // HTTP status code
+console.log(result.headers); // Response headers
+console.log(result.type); // Content-Type
+```
+
+### Automatic JSON Parsing
+
+Superagent automatically parses JSON responses:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+// No need to call .json() - body is already parsed
+const user = result.body; // Already a JavaScript object
+console.log(user.name);
+```
+
+## Error Handling
+
+Superagent throws errors for HTTP error statuses (4xx, 5xx):
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { SuperagentRequestAdapter } from "@flow-conductor/adapter-superagent";
+
+const adapter = new SuperagentRequestAdapter();
+
+try {
+  const result = await begin(
+    {
+      config: {
+        url: "https://api.example.com/users",
+        method: "GET",
+      },
+    },
+    adapter
+  )
+    .withErrorHandler((error) => {
+      console.error("Request failed:", error.message);
+      if (error.status) {
+        console.error("Status:", error.status);
+        console.error("Response:", error.response?.body);
+      }
+    })
+    .execute();
+
+  const data = result.body;
+  console.log(data);
+} catch (error: any) {
+  if (error.status) {
+    // Handle HTTP errors
+    console.error("Status:", error.status);
+    console.error("Response:", error.response?.body);
+  } else {
+    console.error("Error:", error);
+  }
+}
+```
+
+### Error Response Access
+
+Superagent provides detailed error information:
+
+```typescript
+try {
+  await begin(
+    {
+      config: {
+        url: "https://api.example.com/users",
+        method: "GET",
+      },
+    },
+    adapter
+  ).execute();
+} catch (error: any) {
+  if (error.status) {
+    // Server responded with error status
+    console.error("Status:", error.status);
+    console.error("Body:", error.response?.body);
+    console.error("Headers:", error.response?.headers);
+  } else {
+    // Network or other error
+    console.error("Error:", error.message);
+  }
+}
+```
+
+## Examples
+
+### Authentication Flow
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { SuperagentRequestAdapter } from "@flow-conductor/adapter-superagent";
+
+const adapter = new SuperagentRequestAdapter();
+
+// 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: (previousResult) => {
+      const auth = previousResult.body;
+      return {
+        url: "https://api.example.com/user/profile",
+        method: "GET",
+        headers: { Authorization: `Bearer ${auth.token}` },
+      };
+    },
+  })
+  .execute();
+
+const profile = userData.body;
+console.log(profile);
+```
+
+### File Upload
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { SuperagentRequestAdapter } from "@flow-conductor/adapter-superagent";
+
+const adapter = new SuperagentRequestAdapter();
+
+const formData = new FormData();
+formData.append("file", fileBlob);
+formData.append("name", "document.pdf");
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/upload",
+      method: "POST",
+      data: formData,
+    },
+  },
+  adapter
+).execute();
+
+console.log(result.body);
+```
+
+## API Reference
+
+### SuperagentRequestAdapter
+
+```typescript
+class SuperagentRequestAdapter extends RequestAdapter<Response, SuperagentRequestConfig> {
+  createRequest(requestConfig: SuperagentRequestConfig): Promise<Response>;
+}
+```
+
+### SuperagentRequestConfig
+
+```typescript
+type SuperagentRequestConfig = IRequestConfig;
+```
+
+Extends `IRequestConfig` with standard request configuration options.
+
+## Advantages
+
+- **Fluent API**: Clean and intuitive request building
+- **Automatic JSON parsing**: No need to call `.json()` on responses
+- **Cross-platform**: Works in both browser and Node.js
+- **Lightweight**: Smaller bundle size compared to some alternatives
+- **Flexible**: Supports various data formats (JSON, FormData, etc.)
+
+## Requirements
+
+- `@flow-conductor/core` (peer dependency)
+- `superagent` ^8.0.0 (peer dependency)
+- Node.js 18+
+- 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 'superagent';
+
+/**
+ * Request configuration type for Superagent adapter.
+ * Extends IRequestConfig with Superagent-specific options via the index signature.
+ */
+type SuperagentRequestConfig = IRequestConfig & {};
+/**
+ * Request adapter implementation using Superagent as the underlying HTTP client.
+ * Provides a fluent API for building HTTP requests with Superagent.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new SuperagentRequestAdapter();
+ * const chain = begin(
+ *   { config: { url: 'https://api.example.com/users', method: 'GET' } },
+ *   adapter
+ * );
+ * ```
+ */
+declare class SuperagentRequestAdapter extends RequestAdapter<Response, SuperagentRequestConfig> {
+    /**
+     * Creates a new SuperagentRequestAdapter instance.
+     *
+     * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks
+     */
+    constructor(urlValidationOptions?: UrlValidationOptions);
+    /**
+     * Creates and executes an HTTP request using Superagent.
+     * Supports all standard HTTP methods and automatically handles headers and body data.
+     *
+     * @param requestConfig - The request configuration object
+     * @returns A promise that resolves to a Superagent Response object
+     */
+    createRequest(requestConfig: SuperagentRequestConfig): Promise<Response>;
+}
+
+export { type SuperagentRequestConfig, SuperagentRequestAdapter as default };

package/build/index.js

@@ -0,0 +1,62 @@
+import { RequestAdapter } from '@flow-conductor/core';
+import superagent from 'superagent';
+
+// src/superagent-request-adapter.ts
+var SuperagentRequestAdapter = class extends RequestAdapter {
+  /**
+   * Creates a new SuperagentRequestAdapter instance.
+   *
+   * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks
+   */
+  constructor(urlValidationOptions) {
+    super(urlValidationOptions);
+  }
+  /**
+   * Creates and executes an HTTP request using Superagent.
+   * Supports all standard HTTP methods and automatically handles headers and body data.
+   *
+   * @param requestConfig - The request configuration object
+   * @returns A promise that resolves to a Superagent Response object
+   */
+  async createRequest(requestConfig) {
+    const { url, method, data, headers } = requestConfig;
+    let request;
+    const methodLower = method.toLowerCase();
+    switch (methodLower) {
+      case "get":
+        request = superagent.get(url);
+        break;
+      case "post":
+        request = superagent.post(url);
+        break;
+      case "put":
+        request = superagent.put(url);
+        break;
+      case "patch":
+        request = superagent.patch(url);
+        break;
+      case "delete":
+        request = superagent.delete(url);
+        break;
+      case "head":
+        request = superagent.head(url);
+        break;
+      case "options":
+        request = superagent.options(url);
+        break;
+      default:
+        request = superagent(methodLower, url);
+    }
+    if (headers) {
+      request.set(headers);
+    }
+    if (data !== void 0) {
+      request.send(data);
+    }
+    return request;
+  }
+};
+
+export { SuperagentRequestAdapter as default };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/superagent-request-adapter.ts"],"names":[],"mappings":";;;;AA0BA,IAAqB,wBAAA,GAArB,cAAsD,cAAA,CAGpD;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,cACX,aAAA,EACmB;AACnB,IAAA,MAAM,EAAE,GAAA,EAAK,MAAA,EAAQ,IAAA,EAAM,SAAQ,GAAI,aAAA;AAGvC,IAAA,IAAI,OAAA;AACJ,IAAA,MAAM,WAAA,GAAc,OAAO,WAAA,EAAY;AAEvC,IAAA,QAAQ,WAAA;AAAa,MACnB,KAAK,KAAA;AACH,QAAA,OAAA,GAAU,UAAA,CAAW,IAAI,GAAG,CAAA;AAC5B,QAAA;AAAA,MACF,KAAK,MAAA;AACH,QAAA,OAAA,GAAU,UAAA,CAAW,KAAK,GAAG,CAAA;AAC7B,QAAA;AAAA,MACF,KAAK,KAAA;AACH,QAAA,OAAA,GAAU,UAAA,CAAW,IAAI,GAAG,CAAA;AAC5B,QAAA;AAAA,MACF,KAAK,OAAA;AACH,QAAA,OAAA,GAAU,UAAA,CAAW,MAAM,GAAG,CAAA;AAC9B,QAAA;AAAA,MACF,KAAK,QAAA;AACH,QAAA,OAAA,GAAU,UAAA,CAAW,OAAO,GAAG,CAAA;AAC/B,QAAA;AAAA,MACF,KAAK,MAAA;AACH,QAAA,OAAA,GAAU,UAAA,CAAW,KAAK,GAAG,CAAA;AAC7B,QAAA;AAAA,MACF,KAAK,SAAA;AACH,QAAA,OAAA,GAAU,UAAA,CAAW,QAAQ,GAAG,CAAA;AAChC,QAAA;AAAA,MACF;AACE,QAAA,OAAA,GAAU,UAAA,CAAW,aAAa,GAAG,CAAA;AAAA;AAIzC,IAAA,IAAI,OAAA,EAAS;AACX,MAAA,OAAA,CAAQ,IAAI,OAAiC,CAAA;AAAA,IAC/C;AAGA,IAAA,IAAI,SAAS,MAAA,EAAW;AACtB,MAAA,OAAA,CAAQ,KAAK,IAAI,CAAA;AAAA,IACnB;AAEA,IAAA,OAAO,OAAA;AAAA,EACT;AACF","file":"index.js","sourcesContent":["import { RequestAdapter } from \"@flow-conductor/core\";\nimport type {\n  IRequestConfig,\n  UrlValidationOptions,\n} from \"@flow-conductor/core\";\nimport superagent, { type Response, type Request } from \"superagent\";\n\n/**\n * Request configuration type for Superagent adapter.\n * Extends IRequestConfig with Superagent-specific options via the index signature.\n */\nexport type SuperagentRequestConfig = IRequestConfig & {};\n\n/**\n * Request adapter implementation using Superagent as the underlying HTTP client.\n * Provides a fluent API for building HTTP requests with Superagent.\n *\n * @example\n * ```typescript\n * const adapter = new SuperagentRequestAdapter();\n * const chain = begin(\n *   { config: { url: 'https://api.example.com/users', method: 'GET' } },\n *   adapter\n * );\n * ```\n */\nexport default class SuperagentRequestAdapter extends RequestAdapter<\n  Response,\n  SuperagentRequestConfig\n> {\n  /**\n   * Creates a new SuperagentRequestAdapter 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 Superagent.\n   * Supports all standard HTTP methods and automatically handles headers and body data.\n   *\n   * @param requestConfig - The request configuration object\n   * @returns A promise that resolves to a Superagent Response object\n   */\n  public async createRequest(\n    requestConfig: SuperagentRequestConfig\n  ): Promise<Response> {\n    const { url, method, data, headers } = requestConfig;\n\n    // Create the request based on method\n    let request: Request;\n    const methodLower = method.toLowerCase();\n\n    switch (methodLower) {\n      case \"get\":\n        request = superagent.get(url);\n        break;\n      case \"post\":\n        request = superagent.post(url);\n        break;\n      case \"put\":\n        request = superagent.put(url);\n        break;\n      case \"patch\":\n        request = superagent.patch(url);\n        break;\n      case \"delete\":\n        request = superagent.delete(url);\n        break;\n      case \"head\":\n        request = superagent.head(url);\n        break;\n      case \"options\":\n        request = superagent.options(url);\n        break;\n      default:\n        request = superagent(methodLower, url);\n    }\n\n    // Set headers if provided\n    if (headers) {\n      request.set(headers as Record<string, string>);\n    }\n\n    // Set data/body if provided\n    if (data !== undefined) {\n      request.send(data);\n    }\n\n    return request;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@flow-conductor/adapter-superagent",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Superagent 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",
+    "superagent",
+    "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-superagent"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@flow-conductor/core": "^1.0.0",
+    "superagent": "^8.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@flow-conductor/core": "*",
+    "@types/superagent": "^4.1.16",
+    "@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",
+    "superagent": "^8.1.2",
+    "tsx": "^4.7.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1"
+  }
+}