@bff-recipe/types 1.0.0

package/README.md

@@ -0,0 +1,99 @@
+# @bff-recipe/types
+
+TypeScript type definitions for [bff-recipe](https://tayyab23.github.io/bff) — a Backend For Frontend aggregation library for Spring Boot.
+
+This package contains only type definitions. It adds **zero bytes** to your runtime bundle when used with `import type`.
+
+## Install
+
+```bash
+npm install @bff-recipe/types --save-dev
+```
+
+## Usage
+
+### Define your API response types
+
+These come from your backend — OpenAPI codegen, Smithy, or hand-written:
+
+```typescript
+interface Account {
+  accountId: string;
+  billingGroupId: string;
+  plan: 'FREE' | 'PRO' | 'ENTERPRISE';
+}
+
+interface InvoiceList {
+  items: { id: string; amount: number; status: string }[];
+  total: number;
+}
+```
+
+### Type your BFF request and response
+
+```typescript
+import type { RecipeRequest, RecipeResponse } from '@bff-recipe/types';
+import axios from 'axios';
+
+// Define what your recipe returns
+type PaymentsPage = {
+  getAccount: Account;
+  getInvoices: InvoiceList;
+};
+
+// Build the request — RecipeRequest gives you autocomplete on ingredients
+const request: RecipeRequest = {
+  ingredients: [
+    { id: 'getAccount', params: { accountId: 'acc-123' } },
+    {
+      id: 'getInvoices',
+      map: { query: { billingGroupId: 'getAccount::body::${billingGroupId}' } },
+    },
+  ],
+};
+
+// Type the response — each ingredient's body is fully typed
+const { data } = await axios.post<RecipeResponse<PaymentsPage>>(
+  '/bff/payments',
+  request
+);
+
+data.results.getAccount.body.plan;           // ✓ 'FREE' | 'PRO' | 'ENTERPRISE'
+data.results.getInvoices.body.items[0].amount; // ✓ number
+data.results.getAccount.status;              // ✓ number (HTTP status)
+data.results.nonExistent;                    // ✗ compile error
+```
+
+### Works with any HTTP client
+
+The types are framework-agnostic. Use them with whatever you already have:
+
+```typescript
+// fetch
+const res = await fetch('/bff/payments', { method: 'POST', body: JSON.stringify(request) });
+const data: RecipeResponse<PaymentsPage> = await res.json();
+
+// ky
+const data = await ky.post('/bff/payments', { json: request }).json<RecipeResponse<PaymentsPage>>();
+
+// generated SDK
+const data = await sdk.bff.execute<RecipeResponse<PaymentsPage>>(request);
+```
+
+## Exported Types
+
+| Type | Purpose |
+|---|---|
+| `RecipeRequest` | The request body sent to `POST /bff/{recipe}` |
+| `RecipeResponse<T>` | Typed response — maps ingredient IDs to their response bodies |
+| `IngredientResult<T>` | Single ingredient result: `{ status, body }` |
+| `IngredientInput` | Single ingredient in a request: `{ id, params, map, body, ... }` |
+| `DebugInfo` | Debug details when `debug: true` is requested |
+
+## Documentation
+
+Full docs at [tayyab23.github.io/bff](https://tayyab23.github.io/bff)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+export interface IngredientResult<T> {
+    status: number;
+    body: T;
+    type?: string;
+}
+export type RecipeResponse<T extends Record<string, unknown>> = {
+    executionOrder: (string | string[])[];
+    results: {
+        [K in keyof T]: IngredientResult<T[K]>;
+    };
+    debug?: Record<string, DebugInfo>;
+};
+export interface DebugInfo {
+    resolvedRequest: {
+        method: string;
+        path: string;
+        headers: {
+            applied: Record<string, string>;
+            stripped: Record<string, string>;
+        };
+    };
+    resolvedResponse: {
+        headers: Record<string, string>;
+    };
+    durationMs: number;
+}
+export interface IngredientInput {
+    id: string;
+    params?: Record<string, unknown>;
+    body?: unknown;
+    map?: {
+        path?: Record<string, unknown>;
+        query?: Record<string, unknown>;
+        body?: Record<string, unknown>;
+    };
+    dependsOn?: string[];
+    headers?: {
+        forward?: boolean;
+        forwardOnly?: string[];
+        custom?: Record<string, string>;
+        mappings?: Record<string, string>;
+    };
+}
+export interface RecipeRequest {
+    ingredients: IngredientInput[];
+    debug?: boolean;
+    failFast?: boolean;
+    headers?: {
+        forward?: boolean;
+        forwardOnly?: string[];
+    };
+}

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@bff-recipe/types",
+  "version": "1.0.0",
+  "description": "TypeScript type definitions for bff-recipe Spring Boot aggregator",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tayyab23/bff.git",
+    "directory": "bff-client"
+  }
+}