api-client-patterns.mdc

---
description: 
globs: **/*.api-client.ts
alwaysApply: false
---
# API Client Patterns

Guidelines for creating and maintaining API clients that communicate with backend services in the T6C project.

## Client Organization Principles

### One Client Per API Service
- **ALWAYS** create a dedicated client package for each API service
- Client naming convention: `{service-name}-api-client` (e.g., `blog-api-client`, `user-api-client`)
- Service class naming: `{ServiceName}Service` (e.g., `BlogPostService`, `UserService`)

```typescript
// ✅ CORRECT - Dedicated client for blog API
export class BlogPostService extends E.Service<BlogPostService>()(
  '@web/BlogPostService',
  {
    dependencies: [FetchHttpClient.layer],
    effect: E.gen(function* () {
      const client = yield* createHttpClient({
        url: envVars.BLOG_SERVICE_URL,
        apiKey: envVars.BLOG_SERVICE_API_KEY,
      })

      return {
        // ... methods
      }
    }),
  },
) {}
```

## Import Patterns

### Standard Imports
- Always use relative paths for internal imports
- Import types with `type` keyword when used only for typing
- Import schemas without `type` when used for encoding/decoding

```typescript
// ✅ CORRECT - Import patterns
import {
  FetchHttpClient,
  HttpClientRequest,
  HttpClientResponse,
} from '@effect/platform'
import {
  BlogPost,
  BlogPostCategory,
  type BlogPostPatches,
  CreateBlogPostInput,
  GetBlogPageInput,
} from '@t6c/blog-domain'
import {
  type BlogPostId,
  PaginationSchema,
  type SearchParamsSchema,
  type UserId,
} from '@t6c/domain-common'
import { NotFoundError, createHttpClient } from '@t6c/lib-api'
import { Data, Effect as E, Layer, Schema as S } from 'effect'
import { envVars } from '../config.js'
```

## Method Implementation Patterns

### HTTP Method Mapping
- **GET** requests for data retrieval
- **POST** requests for resource creation
- **PUT** requests for resource updates
- **DELETE** requests for resource deletion

```typescript
// ✅ CORRECT - HTTP method usage
createDraft: ({ authorId }: { authorId: UserId }) =>
  HttpClientRequest.post('/v1/blog').pipe(
    HttpClientRequest.bodyJson(CreateBlogPostInput.make({ authorId })),
    // ...
  ),

updateAttributes: (blogPostId: string, patches: BlogPostPatches) =>
  HttpClientRequest.put(`/v1/blog/${blogPostId}`).pipe(
    HttpClientRequest.bodyJson(patches),
    // ...
  ),

delete: (id: string) =>
  HttpClientRequest.del(`/v1/blog/${id}`).pipe(
    // ...
  ),
```

### Request Parameter Handling

#### Path Parameters
- Use template literals for path parameters
- Always validate parameter types

```typescript
// ✅ CORRECT - Path parameters
getById: (blogPostId: string) =>
  HttpClientRequest.get(`/v1/blog/${blogPostId}`).pipe(
    // ...
  ),

like: (blogPostId: BlogPostId, userId: UserId) =>
  HttpClientRequest.get(`/v1/blog/${blogPostId}/like/${userId}`).pipe(
    // ...
  ),
```

#### Query Parameters
- Use `HttpClientRequest.setUrlParams` for query parameters
- Encode complex objects using Schema.encode when needed
- Convert numbers to strings for URL parameters

```typescript
// ✅ CORRECT - Query parameters with schema encoding
getPage: (params: GetBlogPageInput) =>
  S.encode(GetBlogPageInput)(params).pipe(
    E.flatMap((urlParams) =>
      HttpClientRequest.get('/v1/blog').pipe(
        HttpClientRequest.setUrlParams(urlParams),
        client.execute,
      ),
    ),
    // ...
  ),

// ✅ CORRECT - Simple query parameters
search: (input: SearchParamsSchema) =>
  HttpClientRequest.get('/v1/blog/search').pipe(
    HttpClientRequest.setUrlParams({
      query: input.query,
      limit: input.limit.toString(),
      page: input.page.toString(),
    }),
    // ...
  ),
```

#### Request Body
- Use `HttpClientRequest.bodyJson` for JSON payloads
- Always validate request body with schemas

```typescript
// ✅ CORRECT - Request body
createDraft: ({ authorId }: { authorId: UserId }) =>
  HttpClientRequest.post('/v1/blog').pipe(
    HttpClientRequest.bodyJson(CreateBlogPostInput.make({ authorId })),
    // ...
  ),
```

### Response Handling

#### Schema Validation
- **ALWAYS** decode responses using schemas
- Use appropriate response schemas for each endpoint
- Handle pagination responses correctly

```typescript
// ✅ CORRECT - Response decoding
getById: (blogPostId: string) =>
  HttpClientRequest.get(`/v1/blog/${blogPostId}`).pipe(
    client.execute,
    E.flatMap(HttpClientResponse.schemaBodyJson(BlogPost)),
    // ...
  ),

// ✅ CORRECT - Paginated response
getPage: (params: GetBlogPageInput) =>
  // ... request setup
  E.flatMap(
    HttpClientResponse.schemaBodyJson(PaginationSchema(BlogPost)),
  ),
  // ...
```

#### Error Handling
- **ALWAYS** handle 404 errors appropriately
- Use `E.catchIf` for specific error conditions
- Convert HTTP errors to domain errors when appropriate

```typescript
// ✅ CORRECT - 404 error handling
getById: (blogPostId: string) =>
  HttpClientRequest.get(`/v1/blog/${blogPostId}`).pipe(
    client.execute,
    E.flatMap(HttpClientResponse.schemaBodyJson(BlogPost)),
    E.scoped,
    E.catchIf(
      (error) =>
        error._tag === 'ResponseError' && error.response.status === 404,
      () => new NotFoundError({ resource: 'BlogPost', id: blogPostId }),
    ),
    // ...
  ),
```

## Logging and Observability

### Mandatory Logging
- **ALWAYS** log successful responses for debugging
- **ALWAYS** log errors using `E.tapError(E.logError)`
- **ALWAYS** add tracing spans with relevant attributes

```typescript
// ✅ CORRECT - Comprehensive logging and tracing
getById: (blogPostId: string) =>
  HttpClientRequest.get(`/v1/blog/${blogPostId}`).pipe(
    client.execute,
    E.flatMap(HttpClientResponse.schemaBodyJson(BlogPost)),
    E.scoped,
    E.catchIf(
      (error) =>
        error._tag === 'ResponseError' && error.response.status === 404,
      () => new NotFoundError({ resource: 'BlogPost', id: blogPostId }),
    ),
    E.tap((res) => E.logInfo('getById res', JSON.stringify(res))),
    E.tapError(E.logError),
    E.withSpan('get-blog-post-by-id', {
      attributes: {
        blogPostId,
      },
    }),
  ),
```

### Span Naming
- Use kebab-case for span names
- Include relevant context in span attributes
- Match span names to operation purpose

```typescript
// ✅ CORRECT - Span naming
E.withSpan('get-blog-post-by-id', {
  attributes: { blogPostId },
}),

E.withSpan('search-blog-post', {
  attributes: { input },
}),

E.withSpan('update-blog-post-attributes', {
  attributes: { blogPostId, patches },
}),
```

## Method Documentation

### JSDoc Comments
- **ALWAYS** document each client method
- Include HTTP method and endpoint path
- Describe parameters and return types

```typescript
// ✅ CORRECT - Method documentation
/**
 * Get blog post by ID
 * GET /v1/blog/{id}
 */
getById: (blogPostId: string) => // ...

/**
 * Search blog posts
 * GET /v1/blog/search
 */
search: (input: SearchParamsSchema) => // ...

/**
 * Update blog post attributes
 * PUT /v1/blog/{id}
 */
updateAttributes: (blogPostId: string, patches: BlogPostPatches) => // ...
```

## Test Service Implementation

### Mock Service Pattern
- **ALWAYS** provide a test service implementation
- Use `Layer.succeed` for mocking
- Provide sensible defaults that throw for unimplemented methods

```typescript
// ✅ CORRECT - Test service
static makeTestService = (
  mockImplementation: Partial<Omit<BlogPostService, '_tag'>>,
) =>
  Layer.succeed(this, {
    _tag: '@web/BlogPostService',
    createDraft: () => E.die('Not implemented' as const),
    getPage: () => E.die('Not implemented' as const),
    getById: () => E.die('Not implemented' as const),
    // ... all methods with defaults
    ...mockImplementation,
  })
```

## Endpoint Coverage Requirements

### Complete API Coverage
- **MUST** implement ALL endpoints from the corresponding API service
- **MUST** match handler signatures exactly
- **MUST** use correct HTTP methods as defined in handlers
- **MUST** handle all parameter types (path, query, body)

### Validation Checklist
When adding/updating a client, verify:
- [ ] All handlers from `packages/{service}-api/src/lambdas/` are covered
- [ ] HTTP methods match handler implementations
- [ ] Request parameters are correctly encoded
- [ ] Response types are correctly decoded
- [ ] Error handling covers 404 and other expected errors
- [ ] Logging and tracing are implemented
- [ ] JSDoc documentation is complete
- [ ] Test service mock is updated

## Common Patterns

### Void Responses
- Use `E.asVoid` for endpoints that don't return data
- Still log completion for debugging

```typescript
// ✅ CORRECT - Void response
view: (blogPostId: string) =>
  HttpClientRequest.get(`/v1/blog/${blogPostId}/view`).pipe(
    client.execute,
    E.scoped,
    E.asVoid,
    E.tap(() => E.logInfo('view completed', { blogPostId })),
    E.tapError(E.logError),
    E.withSpan('add-view', {
      attributes: { blogPostId },
    }),
  ),
```

### Optional Parameters
- Provide sensible defaults for optional parameters
- Use nullish coalescing for default values

```typescript
// ✅ CORRECT - Optional parameters
getAllTags: (params?: GetTagsInput) =>
  S.encode(GetTagsInput)(params ?? { page: 1, limit: 100 }).pipe(
    // ...
  ),
```

### Configuration
- **ALWAYS** use environment variables from config
- **NEVER** hardcode URLs or API keys
- Use `createHttpClient` helper for consistent setup

```typescript
// ✅ CORRECT - Configuration usage
const client = yield* createHttpClient({
  url: envVars.BLOG_SERVICE_URL,
  apiKey: envVars.BLOG_SERVICE_API_KEY,
})
```