feat: add entity transformer system

Implement flexible entity transformation pipeline with access control and custom transformers. Enables customisation of entity responses through composable transformers for access control, data enrichment, and response modification.

- Add transformer types and base/default implementations
- Update all entity routes to support transformer pipeline
- Add comprehensive tests and snapshots for transformer functionality
- Document transformer system with examples in CLAUDE.md and README.md
- Add @total-typescript/ts-reset for improved type safety
- Clean up package.json dependencies

Author: johnf

CLAUDE.md

@@ -110,6 +110,10 @@ src/
 │   ├── entity.ts       # Single entity operations
 │   ├── entities.ts     # Entity listing/filtering
 │   └── search.ts       # OpenSearch operations
+├── transformers/       # Entity transformers
+│   └── default.ts      # Default entity transformer
+├── types/              # TypeScript type definitions
+│   └── transformers.ts # Transformer type definitions
 ├── utils/              # Utility functions
 │   └── errors.ts       # Error handling helpers
 ├── generated/          # Prisma generated files (excluded from tests)
@@ -160,6 +164,362 @@ src/
 - Validate against OpenAPI specification
 - Handle validation errors gracefully
 
+## Entity Transformers
+
+The API provides a flexible transformer system for customising entity responses. Transformers are applied in a three-stage pipeline:
+
+1. **Base transformer** - Converts database entities to standard format
+2. **Access transformer** - Adds authorisation/access control information
+3. **Entity transformers** - Optional additional transformations
+
+### Overview
+
+The transformer system enables:
+- **Access control**: Control visibility of metadata and content based on licenses
+- **Data enrichment**: Add computed fields or fetch related data
+- **Response customisation**: Adapt the API response to specific client needs
+- **Async operations**: Fetch additional data or perform authorisation checks
+
+### Transformation Pipeline
+
+Every entity response flows through this pipeline:
+
+```
+Database Entity → baseEntityTransformer → accessTransformer → entityTransformers[] → Response
+```
+
+### Usage
+
+When mounting the application, you **must** provide an `accessTransformer`. This is a required security feature to ensure conscious decisions about access control.
+
+```typescript
+import { Client } from '@opensearch-project/opensearch';
+import arocapi, { AllPublicAccessTransformer } from 'arocapi';
+import fastify from 'fastify';
+import { PrismaClient } from './generated/prisma/client.js';
+
+const server = fastify();
+const prisma = new PrismaClient();
+const opensearch = new Client({ node: process.env.OPENSEARCH_URL });
+
+// For fully public datasets, use AllPublicAccessTransformer
+await server.register(arocapi, {
+  prisma,
+  opensearch,
+  accessTransformer: AllPublicAccessTransformer, // Explicit choice for public data
+});
+
+// For restricted content, provide custom accessTransformer
+await server.register(arocapi, {
+  prisma,
+  opensearch,
+  // Required: Controls access to metadata and content
+  accessTransformer: async (entity, { request, fastify }) => {
+    const user = await authenticateUser(request);
+    const canAccessContent = await checkLicense(entity.contentLicenseId, user);
+
+    return {
+      ...entity,
+      access: {
+        metadata: true, // Metadata always visible
+        content: canAccessContent,
+        contentAuthorisationUrl: canAccessContent
+          ? undefined
+          : 'https://example.com/request-access',
+      },
+    };
+  },
+  // Optional: Additional data transformations
+  entityTransformers: [
+    // Add computed fields
+    async (entity) => ({
+      ...entity,
+      displayName: `${entity.name} [${entity.entityType.split('/').pop()}]`,
+    }),
+    // Fetch related data
+    async (entity, { fastify }) => {
+      const collection = entity.memberOf
+        ? await fastify.prisma.entity.findFirst({
+            where: { rocrateId: entity.memberOf },
+          })
+        : null;
+
+      return {
+        ...entity,
+        collection: collection ? { id: collection.rocrateId, name: collection.name } : null,
+      };
+    },
+  ],
+});
+```
+
+### Transformer Types
+
+#### Access Transformer
+
+Controls access to metadata and content. Receives a `StandardEntity` and must return an `AuthorisedEntity`.
+
+```typescript
+type AccessTransformer = (
+  entity: StandardEntity,
+  context: TransformerContext,
+) => Promise<AuthorisedEntity> | AuthorisedEntity;
+
+type StandardEntity = {
+  id: string;
+  name: string;
+  description: string;
+  entityType: string;
+  memberOf: string | null;
+  rootCollection: string | null;
+  metadataLicenseId: string;
+  contentLicenseId: string;
+};
+
+type AuthorisedEntity = StandardEntity & {
+  access: {
+    metadata: boolean;
+    content: boolean;
+    contentAuthorisationUrl?: string;
+  };
+};
+```
+
+#### Entity Transformers
+
+Optional transformations applied after access control. Each transformer receives the output of the previous one.
+
+```typescript
+type EntityTransformer<TInput = AuthorisedEntity, TOutput = TInput> = (
+  entity: TInput,
+  context: TransformerContext,
+) => Promise<TOutput> | TOutput;
+```
+
+#### Transformer Context
+
+All transformers receive a context object:
+
+```typescript
+type TransformerContext = {
+  request: FastifyRequest;  // Access request headers, params, etc.
+  fastify: FastifyInstance; // Access prisma, opensearch, etc.
+};
+```
+
+### AllPublicAccessTransformer
+
+The `AllPublicAccessTransformer` is provided for fully public datasets. It grants full access to all data:
+
+```typescript
+import { AllPublicAccessTransformer } from 'arocapi';
+
+// Returns:
+{
+  ...entity,
+  access: {
+    metadata: true,
+    content: true,
+  },
+}
+```
+
+**Security Note**: The `accessTransformer` parameter is **required**. You must explicitly choose `AllPublicAccessTransformer` for public data or implement a custom transformer for restricted content. This prevents accidental exposure of restricted data.
+
+### Applied Routes
+
+Transformers are applied to all entity routes:
+- `GET /entity/:id` - Single entity
+- `GET /entities` - Entity list (each entity transformed)
+- `POST /search` - Search results (entities + search metadata)
+
+For search results, entities are transformed and then wrapped with search metadata:
+
+```typescript
+{
+  ...transformedEntity,
+  searchExtra: {
+    score: hit._score,
+    highlight: hit.highlight,
+  },
+}
+```
+
+### Examples
+
+#### Access Control with License Checking
+
+```typescript
+accessTransformer: async (entity, { request, fastify }) => {
+  const user = await getUserFromRequest(request);
+
+  // Check if user has access to content license
+  const hasContentAccess = await checkUserLicense(
+    user,
+    entity.contentLicenseId,
+    fastify.prisma,
+  );
+
+  return {
+    ...entity,
+    access: {
+      metadata: true, // Metadata always visible
+      content: hasContentAccess,
+      contentAuthorisationUrl: hasContentAccess
+        ? undefined
+        : `https://rems.example.com/apply?license=${entity.contentLicenseId}`,
+    },
+  };
+}
+```
+
+#### Add Computed Display Name
+
+```typescript
+entityTransformers: [
+  (entity) => ({
+    ...entity,
+    displayName: `${entity.name} [${entity.entityType.split('/').pop()}]`,
+    shortId: entity.id.split('/').pop(),
+  }),
+]
+```
+
+#### Fetch Related Collection Data
+
+```typescript
+entityTransformers: [
+  async (entity, { fastify }) => {
+    if (!entity.memberOf) {
+      return { ...entity, collection: null };
+    }
+
+    const collection = await fastify.prisma.entity.findFirst({
+      where: { rocrateId: entity.memberOf },
+    });
+
+    return {
+      ...entity,
+      collection: collection ? {
+        id: collection.rocrateId,
+        name: collection.name,
+        type: collection.entityType,
+      } : null,
+    };
+  },
+]
+```
+
+#### Combine Access Control and Data Enrichment
+
+```typescript
+await server.register(arocapi, {
+  prisma,
+  opensearch,
+  // Control access based on user authentication
+  accessTransformer: async (entity, { request, fastify }) => {
+    const token = request.headers.authorisation;
+    const user = token ? await verifyToken(token) : null;
+
+    const canAccess = user
+      ? await checkLicense(entity.contentLicenseId, user.id, fastify.prisma)
+      : entity.contentLicenseId === 'http://creativecommons.org/publicdomain/zero/1.0/';
+
+    return {
+      ...entity,
+      access: {
+        metadata: true,
+        content: canAccess,
+      },
+    };
+  },
+  // Add additional computed fields
+  entityTransformers: [
+    (entity) => ({
+      ...entity,
+      displayName: entity.name.toUpperCase(),
+      createdYear: new Date().getFullYear(), // Could fetch from metadata
+    }),
+  ],
+});
+```
+
+#### Request-Specific Data
+
+```typescript
+entityTransformers: [
+  (entity, { request }) => ({
+    ...entity,
+    requestInfo: {
+      timestamp: new Date().toISOString(),
+      userAgent: request.headers['user-agent'],
+      acceptLanguage: request.headers['accept-language'],
+    },
+  }),
+]
+```
+
+### Testing Transformers
+
+Test custom transformers by passing them to your test Fastify instance:
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+import { fastify, fastifyBefore } from './test/helpers/fastify.js';
+import entityRoute from './routes/entity.js';
+
+describe('Custom Transformer Tests', () => {
+  beforeEach(async () => {
+    await fastifyBefore();
+  });
+
+  it('should apply custom access transformer', async () => {
+    const customAccessTransformer = (entity) => ({
+      ...entity,
+      access: {
+        metadata: true,
+        content: false, // Restrict content access
+        contentAuthorisationUrl: 'https://example.com/request',
+      },
+    });
+
+    await fastify.register(entityRoute, {
+      accessTransformer: customAccessTransformer,
+    });
+
+    const response = await fastify.inject({
+      method: 'GET',
+      url: '/entity/http://example.com/test',
+    });
+
+    const body = JSON.parse(response.body);
+    expect(body.access.content).toBe(false);
+  });
+
+  it('should apply custom entity transformers', async () => {
+    const customTransformer = (entity) => ({
+      ...entity,
+      tested: true,
+      displayName: entity.name.toUpperCase(),
+    });
+
+    await fastify.register(entityRoute, {
+      accessTransformer: AllPublicAccessTransformer,
+      entityTransformers: [customTransformer],
+    });
+
+    const response = await fastify.inject({
+      method: 'GET',
+      url: '/entity/http://example.com/test',
+    });
+
+    const body = JSON.parse(response.body);
+    expect(body.tested).toBe(true);
+    expect(body.displayName).toBe('TEST ENTITY');
+  });
+});
+```
+
 ## Database Management
 
 ### Prisma Operations