@fnd-platform/api 1.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 fnd-platform contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# @fnd-platform/api
+
+Projen project class and runtime utilities for building serverless Lambda APIs with type-safe handlers, middleware patterns, and DynamoDB integration.
+
+## Installation
+
+```bash
+npm install -D @fnd-platform/api
+# or
+pnpm add -D @fnd-platform/api
+```
+
+## Quick Start
+
+Add an API package to your monorepo in `.projenrc.ts`:
+
+```typescript
+import { FndMonorepoProject } from '@fnd-platform/core';
+import { FndApiProject } from '@fnd-platform/api';
+
+const monorepo = new FndMonorepoProject({
+  name: 'my-app',
+  defaultReleaseBranch: 'main',
+});
+
+const api = new FndApiProject({
+  parent: monorepo,
+  name: 'api',
+  outdir: 'packages/api',
+  dynamodb: true,
+  cognito: true,
+});
+
+monorepo.synth();
+```
+
+## Configuration Options
+
+| Option     | Type                 | Default           | Description                    |
+| ---------- | -------------------- | ----------------- | ------------------------------ |
+| `parent`   | `FndMonorepoProject` | **required**      | Parent monorepo                |
+| `name`     | `string`             | **required**      | Package name                   |
+| `outdir`   | `string`             | `packages/{name}` | Output directory               |
+| `dynamodb` | `boolean`            | `true`            | Include DynamoDB utilities     |
+| `cognito`  | `boolean`            | `true`            | Include Cognito authentication |
+| `cors`     | `boolean`            | `true`            | Enable CORS support            |
+
+## Features
+
+- **Lambda Handlers** - Type-safe handler patterns with middleware support
+- **Response Helpers** - Consistent JSON responses with proper status codes
+- **Error Classes** - Structured error handling with automatic response mapping
+- **Middleware Composition** - Composable middleware for auth, validation, CORS, logging
+- **Request Utilities** - Parse body, path params, query params, and user context
+
+## Examples
+
+### Basic Handler
+
+```typescript
+import { APIGatewayProxyHandler } from 'aws-lambda';
+import { success, notFound } from '@fnd-platform/api';
+
+export const handler: APIGatewayProxyHandler = async (event) => {
+  const data = { message: 'Hello, World!' };
+  return success(data);
+};
+```
+
+### Handler with Middleware
+
+```typescript
+import { compose, withAuth, withErrorHandler, withValidation } from '@fnd-platform/api';
+import { z } from 'zod';
+
+const schema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string(),
+});
+
+export const handler = compose(
+  withErrorHandler(),
+  withAuth(),
+  withValidation(schema)
+)(async (event) => {
+  const body = JSON.parse(event.body || '{}');
+  // body is validated against schema
+  return success({ id: '123', ...body }, 201);
+});
+```
+
+### Using Request Utilities
+
+```typescript
+import { requirePathParam, getQueryParam, parseBody, getUserId } from '@fnd-platform/api';
+
+export const handler = withAuth(async (event) => {
+  const id = requirePathParam(event, 'id');
+  const page = getQueryParam(event, 'page', '1');
+  const body = parseBody(event);
+  const userId = getUserId(event);
+
+  // ... handler logic
+});
+```
+
+## API Reference
+
+See the [full API documentation](../../docs/api/modules/api_src.html) for detailed type definitions and examples.
+
+### Project Class
+
+- `FndApiProject` - Projen project class for API packages
+
+### Response Helpers
+
+```typescript
+import {
+  success, // 200 OK (or custom status)
+  created, // 201 Created
+  error, // 500 Internal Server Error (or custom)
+  notFound, // 404 Not Found
+  unauthorized, // 401 Unauthorized
+  forbidden, // 403 Forbidden
+  badRequest, // 400 Bad Request
+} from '@fnd-platform/api';
+```
+
+### Error Classes
+
+```typescript
+import {
+  ApiError, // Base error class
+  NotFoundError, // 404 errors
+  ValidationError, // 400/422 validation errors
+  UnauthorizedError, // 401 errors
+  ForbiddenError, // 403 errors
+  ConflictError, // 409 conflict errors
+} from '@fnd-platform/api';
+```
+
+### Middleware
+
+```typescript
+import {
+  compose, // Compose multiple middleware
+  withErrorHandler, // Catch errors and return proper responses
+  withAuth, // Validate JWT tokens from Cognito
+  withValidation, // Validate request body with Zod
+  withCors, // Add CORS headers
+  withLogging, // Log requests and responses
+} from '@fnd-platform/api';
+```
+
+### Request Utilities
+
+```typescript
+import {
+  parseBody, // Parse JSON body
+  requirePathParam, // Get required path parameter
+  getQueryParam, // Get query parameter with default
+  getUserId, // Get authenticated user ID
+} from '@fnd-platform/api';
+```
+
+### Types
+
+```typescript
+import type {
+  FndApiProjectOptions,
+  Handler,
+  AuthenticatedEvent,
+  AuthenticatedHandler,
+  CognitoClaims,
+  PaginatedRequest,
+  PaginatedResponse,
+  MiddlewareHandler,
+  Middleware,
+  ValidatedEvent,
+  SuccessResponse,
+  ErrorResponse,
+  ErrorHandlerOptions,
+  AuthOptions,
+  CorsOptions,
+  LoggingOptions,
+} from '@fnd-platform/api';
+```
+
+## Requirements
+
+- Node.js 20+
+- pnpm 8+
+- @fnd-platform/core
+
+## Related
+
+- [@fnd-platform/core](../core/README.md) - Core Projen project classes
+- [@fnd-platform/dynamodb](../dynamodb/README.md) - DynamoDB utilities
+- [@fnd-platform/cognito-auth](../cognito-auth/README.md) - Cognito authentication
+- [@fnd-platform/constructs](../constructs/README.md) - CDK constructs for deployment
+
+## License
+
+MIT

package/lib/api-project.d.ts

@@ -0,0 +1,99 @@
+import { typescript } from 'projen';
+import type { FndMonorepoProject } from '@fnd-platform/core';
+import type { FndApiProjectOptions } from './options';
+/**
+ * Creates a Lambda API package within an fnd-platform monorepo.
+ *
+ * This class generates a complete API package scaffold with:
+ * - Lambda handler templates
+ * - Response helper utilities
+ * - Error handling classes
+ * - TypeScript types for API interactions
+ *
+ * Files are generated using Projen's SampleFile, allowing users to modify
+ * them after generation while still maintaining the project structure.
+ *
+ * @example
+ * ```typescript
+ * import { FndMonorepoProject } from '@fnd-platform/core';
+ * import { FndApiProject } from '@fnd-platform/api';
+ *
+ * const monorepo = new FndMonorepoProject({
+ *   name: 'my-app',
+ *   defaultReleaseBranch: 'main',
+ * });
+ *
+ * const api = new FndApiProject({
+ *   parent: monorepo,
+ *   name: 'api',
+ * });
+ *
+ * monorepo.synth();
+ * ```
+ */
+export declare class FndApiProject extends typescript.TypeScriptProject {
+  /**
+   * Reference to the parent monorepo project.
+   */
+  readonly parentProject: FndMonorepoProject;
+  /**
+   * Whether DynamoDB integration is enabled.
+   */
+  readonly dynamodbEnabled: boolean;
+  /**
+   * Whether Cognito auth integration is enabled.
+   */
+  readonly cognitoEnabled: boolean;
+  /**
+   * Whether CORS is enabled.
+   */
+  readonly corsEnabled: boolean;
+  /**
+   * Creates a new FndApiProject.
+   *
+   * @param options - Configuration options for the API project
+   * @throws {Error} If required options are missing
+   */
+  constructor(options: FndApiProjectOptions);
+  /**
+   * Adds API-specific dependencies to the project.
+   */
+  private addApiDependencies;
+  /**
+   * Generates the handlers directory with Lambda handler templates.
+   */
+  private generateHandlersDirectory;
+  /**
+   * Generates the lib directory with utility files.
+   */
+  private generateLibDirectory;
+  /**
+   * Generates the types directory with TypeScript type definitions.
+   */
+  private generateTypesDirectory;
+  /**
+   * Returns the health handler template content.
+   */
+  private getHealthHandlerTemplate;
+  /**
+   * Returns the response helpers template content.
+   */
+  private getResponseTemplate;
+  /**
+   * Returns the error classes template content.
+   */
+  private getErrorsTemplate;
+  /**
+   * Returns the middleware template content.
+   */
+  private getMiddlewareTemplate;
+  /**
+   * Returns the API types template content.
+   */
+  private getApiTypesTemplate;
+  /**
+   * Returns the entity types template content.
+   */
+  private getEntityTypesTemplate;
+}
+//# sourceMappingURL=api-project.d.ts.map

package/lib/api-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-project.d.ts","sourceRoot":"","sources":["../src/api-project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA0B,MAAM,QAAQ,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAItD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,aAAc,SAAQ,UAAU,CAAC,iBAAiB;IAC7D;;OAEG;IACH,SAAgB,aAAa,EAAE,kBAAkB,CAAC;IAElD;;OAEG;IACH,SAAgB,eAAe,EAAE,OAAO,CAAC;IAEzC;;OAEG;IACH,SAAgB,cAAc,EAAE,OAAO,CAAC;IAExC;;OAEG;IACH,SAAgB,WAAW,EAAE,OAAO,CAAC;IAErC;;;;;OAKG;gBACS,OAAO,EAAE,oBAAoB;IA0DzC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAOjC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiB5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAoBhC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA0I3B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkGzB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA8E7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAsE3B;;OAEG;IACH,OAAO,CAAC,sBAAsB;CA2F/B"}