arocapi 1.1.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/LICENSE.md +5 -0
  2. package/README.md +459 -36
  3. package/dist/app.d.ts +19 -1
  4. package/dist/app.js +37 -29
  5. package/dist/app.js.map +1 -1
  6. package/dist/app.test.js +124 -0
  7. package/dist/app.test.js.map +1 -0
  8. package/dist/index.dev.js +146 -0
  9. package/dist/index.dev.js.map +1 -0
  10. package/dist/routes/crate.d.ts +7 -0
  11. package/dist/routes/crate.js +101 -0
  12. package/dist/routes/crate.js.map +1 -0
  13. package/dist/routes/crate.test.d.ts +1 -0
  14. package/dist/routes/crate.test.js +360 -0
  15. package/dist/routes/crate.test.js.map +1 -0
  16. package/dist/routes/entities.d.ts +6 -1
  17. package/dist/routes/entities.js +52 -39
  18. package/dist/routes/entities.js.map +1 -1
  19. package/dist/routes/entities.test.d.ts +1 -0
  20. package/dist/routes/entities.test.js +245 -0
  21. package/dist/routes/entities.test.js.map +1 -0
  22. package/dist/routes/entity.d.ts +6 -1
  23. package/dist/routes/entity.js +30 -8
  24. package/dist/routes/entity.js.map +1 -1
  25. package/dist/routes/entity.test.d.ts +1 -0
  26. package/dist/routes/entity.test.js +109 -0
  27. package/dist/routes/entity.test.js.map +1 -0
  28. package/dist/routes/file.d.ts +7 -0
  29. package/dist/routes/file.js +113 -0
  30. package/dist/routes/file.js.map +1 -0
  31. package/dist/routes/file.test.d.ts +1 -0
  32. package/dist/routes/file.test.js +319 -0
  33. package/dist/routes/file.test.js.map +1 -0
  34. package/dist/routes/files.d.ts +8 -0
  35. package/dist/routes/files.js +62 -0
  36. package/dist/routes/files.js.map +1 -0
  37. package/dist/routes/files.test.d.ts +1 -0
  38. package/dist/routes/files.test.js +244 -0
  39. package/dist/routes/files.test.js.map +1 -0
  40. package/dist/routes/search.d.ts +6 -1
  41. package/dist/routes/search.js +44 -19
  42. package/dist/routes/search.js.map +1 -1
  43. package/dist/routes/search.test.d.ts +1 -0
  44. package/dist/routes/search.test.js +698 -0
  45. package/dist/routes/search.test.js.map +1 -0
  46. package/dist/test/helpers/fastify.d.ts +9 -0
  47. package/dist/test/helpers/fastify.js +24 -0
  48. package/dist/test/helpers/fastify.js.map +1 -0
  49. package/dist/test/integration.setup.d.ts +58 -0
  50. package/dist/test/integration.setup.js +181 -0
  51. package/dist/test/integration.setup.js.map +1 -0
  52. package/dist/test/integration.test.d.ts +1 -0
  53. package/dist/test/integration.test.js +337 -0
  54. package/dist/test/integration.test.js.map +1 -0
  55. package/dist/transformers/default.d.ts +45 -0
  56. package/dist/transformers/default.js +46 -0
  57. package/dist/transformers/default.js.map +1 -0
  58. package/dist/transformers/default.test.d.ts +1 -0
  59. package/dist/transformers/default.test.js +177 -0
  60. package/dist/transformers/default.test.js.map +1 -0
  61. package/dist/transformers/transformer.test.d.ts +1 -0
  62. package/dist/transformers/transformer.test.js +176 -0
  63. package/dist/transformers/transformer.test.js.map +1 -0
  64. package/dist/types/fileHandlers.d.ts +41 -0
  65. package/dist/types/fileHandlers.js +2 -0
  66. package/dist/types/fileHandlers.js.map +1 -0
  67. package/dist/types/transformers.d.ts +10 -0
  68. package/dist/types/transformers.js +2 -0
  69. package/dist/types/transformers.js.map +1 -0
  70. package/dist/utils/errors.d.ts +23 -0
  71. package/dist/utils/errors.js +21 -0
  72. package/dist/utils/errors.js.map +1 -0
  73. package/dist/utils/errors.test.d.ts +1 -0
  74. package/dist/utils/errors.test.js +66 -0
  75. package/dist/utils/errors.test.js.map +1 -0
  76. package/package.json +35 -28
  77. package/prisma/migrations/20250827033956_record_type_scalar/migration.sql +10 -0
  78. package/prisma/migrations/20250923032753_api_refactor/migration.sql +39 -0
  79. package/prisma/migrations/20250923223119_entity_type_to_string/migration.sql +8 -0
  80. package/prisma/migrations/20251020140329_add_meta_column/migration.sql +2 -0
  81. package/prisma/migrations/20251027010713_add_file_table/migration.sql +17 -0
  82. package/prisma/migrations/20251027221138_add_file_id_to_entity/migration.sql +2 -0
  83. package/prisma/models/entity.prisma +16 -12
  84. package/prisma/models/file.prisma +20 -0
  85. package/prisma.config.ts +6 -1
  86. package/src/__snapshots__/app.test.ts.snap +8 -0
  87. package/src/app.test.ts +158 -0
  88. package/src/app.ts +99 -36
  89. package/src/index.dev.ts +196 -0
  90. package/src/reset.d.ts +1 -0
  91. package/src/routes/__snapshots__/entities.test.ts.snap +68 -0
  92. package/src/routes/__snapshots__/entity.test.ts.snap +57 -0
  93. package/src/routes/__snapshots__/search.test.ts.snap +139 -0
  94. package/src/routes/crate.test.ts +441 -0
  95. package/src/routes/crate.ts +145 -0
  96. package/src/routes/entities.test.ts +284 -0
  97. package/src/routes/entities.ts +69 -48
  98. package/src/routes/entity.test.ts +132 -0
  99. package/src/routes/entity.ts +59 -22
  100. package/src/routes/file.test.ts +399 -0
  101. package/src/routes/file.ts +157 -0
  102. package/src/routes/files.test.ts +303 -0
  103. package/src/routes/files.ts +89 -0
  104. package/src/routes/search.test.ts +807 -0
  105. package/src/routes/search.ts +67 -25
  106. package/src/test/__snapshots__/integration.test.ts.snap +18 -0
  107. package/src/test/helpers/fastify.ts +39 -0
  108. package/src/test/integration.setup.ts +200 -0
  109. package/src/test/integration.test.ts +411 -0
  110. package/src/transformers/default.test.ts +199 -0
  111. package/src/transformers/default.ts +165 -0
  112. package/src/transformers/transformer.test.ts +233 -0
  113. package/src/types/fileHandlers.ts +65 -0
  114. package/src/types/transformers.ts +52 -0
  115. package/src/utils/errors.test.ts +75 -0
  116. package/src/utils/errors.ts +45 -0
  117. package/dist/index.js +0 -25
  118. package/dist/index.js.map +0 -1
  119. package/dist/scripts/loadEntities.js +0 -170
  120. package/dist/scripts/loadEntities.js.map +0 -1
  121. package/dist/type.d.ts +0 -6
  122. package/dist/type.js +0 -2
  123. package/dist/type.js.map +0 -1
  124. package/src/index.ts +0 -35
  125. package/src/scripts/loadEntities.ts +0 -223
  126. package/src/type.ts +0 -7
  127. /package/dist/{scripts/loadEntities.d.ts → app.test.d.ts} +0 -0
  128. /package/dist/{index.d.ts → index.dev.d.ts} +0 -0
package/LICENSE.md ADDED
@@ -0,0 +1,5 @@
1
+ Copyright 2025 TBA
2
+
3
+ Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
4
+
5
+ THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
package/README.md CHANGED
@@ -1,4 +1,3 @@
1
-
2
1
  # An RO-Crate API for Data Collections : Arocapi
3
2
 
4
3
  This project a prototype implementation of an RO-Crate based collections
@@ -73,11 +72,12 @@ OPENSEARCH_URL="http://localhost:9200"
73
72
  Create your Fastify application with Typescript support:
74
73
 
75
74
  ```typescript
76
- // src/app.ts
75
+ // src/index.ts
77
76
  import { Client } from '@opensearch-project/opensearch';
78
- import arocapi from 'arocapi';
79
- import type { FastifyPluginAsync } from 'fastify';
77
+ import arocapi, { AllPublicAccessTransformer, AllPublicFileAccessTransformer } from 'arocapi';
78
+ import Fastify from 'fastify';
80
79
  import { PrismaClient } from './generated/prisma/client.js';
80
+ import { Readable } from 'stream';
81
81
 
82
82
  // NOTE: Only needed if you are going to use these yourself
83
83
  declare module 'fastify' {
@@ -98,7 +98,43 @@ const opensearch = new Client({ node: opensearchUrl });
98
98
  const fastify = Fastify({
99
99
  logger: true,
100
100
  });
101
- fastify.register(arocapi, { prisma, opensearch });
101
+
102
+ // For fully public datasets
103
+ fastify.register(arocapi, {
104
+ prisma,
105
+ opensearch,
106
+ accessTransformer: AllPublicAccessTransformer,
107
+ fileAccessTransformer: AllPublicFileAccessTransformer,
108
+ // Required: File handler for serving File entity content
109
+ fileHandler: {
110
+ get: async (file) => {
111
+ const fileUrl = `https://storage.example.com/${file.meta.storagePath}`;
112
+ return { type: 'redirect', url: fileUrl };
113
+ },
114
+ head: async (file) => ({
115
+ contentType: file.mediaType,
116
+ contentLength: file.size,
117
+ }),
118
+ },
119
+ // Required: RO-Crate handler for serving RO-Crate metadata
120
+ roCrateHandler: {
121
+ get: async (entity) => {
122
+ const jsonString = JSON.stringify(entity.rocrate, null, 2);
123
+ return {
124
+ type: 'stream',
125
+ stream: Readable.from([jsonString]),
126
+ metadata: {
127
+ contentType: 'application/ld+json',
128
+ contentLength: Buffer.byteLength(jsonString),
129
+ },
130
+ };
131
+ },
132
+ head: async (entity) => ({
133
+ contentType: 'application/ld+json',
134
+ contentLength: Buffer.byteLength(JSON.stringify(entity.rocrate)),
135
+ }),
136
+ },
137
+ });
102
138
 
103
139
  try {
104
140
  await fastify.listen({ port: 3000 });
@@ -151,7 +187,7 @@ npx prisma init --datasource-provider mysql
151
187
 
152
188
  ### 2. Configure Prisma Multi-Model Setup
153
189
 
154
- Create a `prisma.config.ts` file in your project root:
190
+ Modify the `prisma.config.ts` file in your project root to support folder based schemas:
155
191
 
156
192
  ```typescript
157
193
  // prisma.config.ts
@@ -159,6 +195,7 @@ import 'dotenv/config';
159
195
  import { defineConfig } from 'prisma/config';
160
196
 
161
197
  export default defineConfig({
198
+ // Adds support for folder based schemas
162
199
  schema: 'prisma',
163
200
  });
164
201
  ```
@@ -172,54 +209,440 @@ Create the directory structure and link to arocapi models:
172
209
  mkdir -p prisma/models
173
210
 
174
211
  # Link to the upstream arocapi models
175
- cd prisma && ln -s ../node_modules/arocapi/prisma/models upstream && cd ..
212
+ ln -s ../../node_modules/arocapi/prisma/models prisma/arocapi
213
+ ```
214
+
215
+ ### 4. Generate Prisma Client and Run Migrations
216
+
217
+ ```bash
218
+ # Create database migrations for this version of arocapi
219
+ npx prisma migrate dev --name="arocapi-$(pnpm list | grep arocapi | awk '{ print $2 }')"
220
+
221
+ # Generate the Prisma client
222
+ npx prisma generate
223
+
224
+ ```
225
+
226
+ ## Available API Routes
227
+
228
+ The arocapi provides the following endpoints:
229
+
230
+ - `GET /entities` - List all entities with pagination and filtering
231
+ - `GET /entity/:id` - Get a specific entity by ID
232
+ - `GET /entity/:id/rocrate` - Download RO-Crate metadata
233
+ - `GET /files` - List files with pagination and filtering
234
+ - `GET /file/:id` - Download or access file content
235
+ - `POST /search` - Search entities using OpenSearch
236
+
237
+ ## Customising Entity Responses
238
+
239
+ The API provides a flexible transformer system for customising entity responses
240
+ through two types of transformers:
241
+
242
+ ### Access Transformer (Required)
243
+
244
+ The `accessTransformer` parameter is **required** for security. You must explicitly
245
+ choose how access control is handled for your repository.
246
+
247
+ **For fully public datasets**, use `AllPublicAccessTransformer`:
248
+
249
+ ```typescript
250
+ import arocapi, { AllPublicAccessTransformer } from 'arocapi';
251
+
252
+ await server.register(arocapi, {
253
+ prisma,
254
+ opensearch,
255
+ accessTransformer: AllPublicAccessTransformer,
256
+ });
257
+ ```
258
+
259
+ **For restricted content**, implement a custom access transformer:
260
+
261
+ ```typescript
262
+ const accessTransformer = async (entity, { request, fastify }) => {
263
+ // Custom logic to determine access
264
+ const user = await authenticateUser(request);
265
+ const canAccessContent = await checkLicense(entity.contentLicenseId, user);
266
+
267
+ return {
268
+ ...entity,
269
+ access: {
270
+ metadata: true, // Metadata always visible
271
+ content: canAccessContent,
272
+ contentAuthorisationUrl: canAccessContent
273
+ ? undefined
274
+ : 'https://rems.example.com/request-access',
275
+ },
276
+ };
277
+ };
278
+ ```
279
+
280
+ > [!WARNING]
281
+ > The `accessTransformer` is required to prevent accidental exposure of
282
+ > restricted content. You must make an explicit choice about access control for
283
+ > your repository.
284
+
285
+ ### Entity Transformers
286
+
287
+ Optional transformations for enriching or modifying response data. Multiple
288
+ transformers can be chained together.
289
+
290
+ ```typescript
291
+ await server.register(arocapi, {
292
+ prisma,
293
+ opensearch,
294
+ accessTransformer: AllPublicAccessTransformer,
295
+ entityTransformers: [
296
+ // Add computed fields
297
+ (entity) => ({
298
+ ...entity,
299
+ displayName: `${entity.name} [${entity.entityType.split('/').pop()}]`,
300
+ }),
301
+ // Add counts
302
+ async (entity, { fastify }) => {
303
+ const objectCount = entity.memberOf
304
+ ? await fastify.prisma.entity.count({
305
+ where: { memberOf: entity.rocrateId },
306
+ })
307
+ : 0;
308
+
309
+ return {
310
+ ...entity,
311
+ counts: {
312
+ objects: objectCount,
313
+ }
314
+ };
315
+ },
316
+ ],
317
+ });
318
+ ```
319
+
320
+ ### Transformation Pipeline
321
+
322
+ Every entity response flows through this three-stage pipeline:
323
+
324
+ 1. **Base transformer** - Converts database entities to standard format
325
+ 2. **Access transformer** - Adds access control information
326
+ 3. **Entity transformers** - Optional additional transformations
327
+
328
+ ### Common Use Cases
329
+
330
+ **Access control for restricted content:**
331
+
332
+ ```typescript
333
+ accessTransformer: async (entity, { request, fastify }) => {
334
+ const hasAccess = await checkUserPermissions(request, entity.contentLicenseId);
335
+ return {
336
+ ...entity,
337
+ access: {
338
+ metadata: true,
339
+ content: hasAccess,
340
+ },
341
+ };
342
+ }
343
+ ```
344
+
345
+ **Adding computed or derived fields:**
346
+
347
+ ```typescript
348
+ entityTransformers: [
349
+ (entity) => ({
350
+ ...entity,
351
+ shortId: entity.id.split('/').pop(),
352
+ year: extractYear(entity.description),
353
+ }),
354
+ ]
355
+ ```
356
+
357
+ **Fetching related data asynchronously:**
358
+
359
+ ```typescript
360
+ entityTransformers: [
361
+ async (entity, { fastify }) => ({
362
+ ...entity,
363
+ stats: await fetchEntityStats(entity.id, fastify.prisma),
364
+ }),
365
+ ]
366
+ ```
367
+
368
+ ## Customising File Responses
369
+
370
+ The API provides a separate transformer system for file responses, similar to entity transformers but specifically designed for files.
371
+
372
+ ### File Access Transformer (Required)
373
+
374
+ The `fileAccessTransformer` parameter is **required** for security. You must explicitly choose how access control is handled for file content.
375
+
376
+ **Key Difference from Entity Transformers**: File metadata (filename, size, mediaType, etc.) is always accessible. Only content access is controlled via the `access.content` field.
377
+
378
+ **For fully public datasets**, use `AllPublicFileAccessTransformer`:
379
+
380
+ ```typescript
381
+ import arocapi, { AllPublicAccessTransformer, AllPublicFileAccessTransformer } from 'arocapi';
382
+
383
+ await server.register(arocapi, {
384
+ prisma,
385
+ opensearch,
386
+ accessTransformer: AllPublicAccessTransformer,
387
+ fileAccessTransformer: AllPublicFileAccessTransformer,
388
+ });
389
+ ```
390
+
391
+ **For restricted content**, implement a custom file access transformer:
392
+
393
+ ```typescript
394
+ const fileAccessTransformer = async (file, { request, fastify }) => {
395
+ // Custom logic to determine file content access
396
+ const user = await authenticateUser(request);
397
+ const canAccessContent = await checkLicense(file.contentLicenseId, user);
398
+
399
+ return {
400
+ ...file,
401
+ access: {
402
+ content: canAccessContent,
403
+ contentAuthorizationUrl: canAccessContent
404
+ ? undefined
405
+ : 'https://rems.example.com/request-access',
406
+ },
407
+ };
408
+ };
409
+
410
+ await server.register(arocapi, {
411
+ prisma,
412
+ opensearch,
413
+ accessTransformer: AllPublicAccessTransformer,
414
+ fileAccessTransformer,
415
+ });
416
+ ```
417
+
418
+ > [!WARNING]
419
+ > The `fileAccessTransformer` is required to prevent accidental exposure of
420
+ > restricted file content. You must make an explicit choice about access control
421
+ > for your files.
422
+
423
+ ### File Transformers
424
+
425
+ Optional transformations for enriching or modifying file response data. Multiple
426
+ file transformers can be chained together.
427
+
428
+ ```typescript
429
+ await server.register(arocapi, {
430
+ prisma,
431
+ opensearch,
432
+ accessTransformer: AllPublicAccessTransformer,
433
+ fileAccessTransformer: AllPublicFileAccessTransformer,
434
+ fileTransformers: [
435
+ // Add computed fields
436
+ (file) => ({
437
+ ...file,
438
+ displayFilename: file.filename.toUpperCase(),
439
+ sizeInKB: Math.round(file.size / 1024),
440
+ extension: file.filename.split('.').pop(),
441
+ }),
442
+ // Fetch parent entity information
443
+ async (file, { fastify }) => {
444
+ const parent = await fastify.prisma.entity.findFirst({
445
+ where: { rocrateId: file.memberOf },
446
+ });
447
+
448
+ return {
449
+ ...file,
450
+ parentEntity: parent ? {
451
+ id: parent.rocrateId,
452
+ name: parent.name,
453
+ type: parent.entityType,
454
+ } : null,
455
+ };
456
+ },
457
+ ],
458
+ });
176
459
  ```
177
460
 
178
- ### 4. Configure Prisma Schema
461
+ ### File Transformation Pipeline
462
+
463
+ Every file response flows through this three-stage pipeline:
464
+
465
+ 1. **Base file transformer** - Converts database File records to standard format
466
+ 2. **File access transformer** - Adds access control information (content only)
467
+ 3. **File transformers** - Optional additional transformations
468
+
469
+ ### Applied Routes
470
+
471
+ File transformers are applied to the files listing route:
472
+
473
+ - `GET /files` - File list (each file transformed)
474
+
475
+ **Note**: The `/file/:id` endpoint (for downloading file content) uses the `fileHandler` system, not file transformers. See the File Handler System section below for details.
476
+
477
+ ## File Handler System
478
+
479
+ The API provides two separate handler systems for serving different types of content. These are distinct from the file transformer system described above.
480
+
481
+ **Important Distinction:**
482
+
483
+ - **File Transformers** (above) - Transform file metadata in the `/files` listing endpoint response
484
+ - **File Handler** (this section) - Serves actual file content via the `/file/:id` download endpoint
485
+ - **RO-Crate Handler** (this section) - Serves RO-Crate metadata via the `/entity/:id/rocrate` endpoint
486
+
487
+ ### File Handler (Required)
488
+
489
+ The `fileHandler` parameter is **required**. It serves actual file content for the `/file/:id` endpoint.
490
+
491
+ This handler is responsible for:
492
+
493
+ - Streaming file content from your storage backend
494
+ - Generating redirect URLs to external storage (S3, CDN, etc.)
495
+ - Implementing access control for file downloads
496
+ - Supporting HTTP range requests for media streaming
497
+
498
+ ### RO-Crate Handler (Required)
179
499
 
180
- Update your `prisma/schema.prisma` file:
500
+ The `roCrateHandler` parameter is **required**. It serves RO-Crate metadata as JSON-LD
501
+ for any entity type (Collection, Object, or File) via the `/entity/:id/rocrate` endpoint.
181
502
 
182
- ```prisma
183
- // prisma/schema.prisma
184
- generator client {
185
- provider = "prisma-client"
186
- output = "../src/generated/prisma"
187
- importFileExtension = "js"
503
+ **File Handler Example** (S3 with redirect):
504
+
505
+ ```typescript
506
+ fileHandler: {
507
+ get: async (file) => {
508
+ const command = new GetObjectCommand({
509
+ Bucket: file.meta.bucket,
510
+ Key: file.meta.s3Key,
511
+ });
512
+ const url = await getSignedUrl(s3, command, { expiresIn: 3600 });
513
+
514
+ return { type: 'redirect', url };
515
+ },
516
+ head: async (file) => {
517
+ return {
518
+ contentType: file.mediaType,
519
+ contentLength: file.size,
520
+ };
521
+ },
188
522
  }
523
+ ```
524
+
525
+ **File Handler Example** (local filesystem):
189
526
 
190
- generator json {
191
- provider = "prisma-json-types-generator"
527
+ ```typescript
528
+ fileHandler: {
529
+ get: async (file) => {
530
+ const filePath = `/data/files/${file.meta.storagePath}`;
531
+ const stats = await stat(filePath);
532
+
533
+ return {
534
+ type: 'stream',
535
+ stream: createReadStream(filePath),
536
+ metadata: {
537
+ contentType: file.mediaType,
538
+ contentLength: stats.size,
539
+ lastModified: stats.mtime,
540
+ },
541
+ };
542
+ },
543
+ head: async (file) => {
544
+ const filePath = `/data/files/${file.meta.storagePath}`;
545
+ const stats = await stat(filePath);
546
+
547
+ return {
548
+ contentType: file.mediaType,
549
+ contentLength: stats.size,
550
+ lastModified: stats.mtime,
551
+ };
552
+ },
192
553
  }
554
+ ```
193
555
 
194
- datasource db {
195
- provider = "mysql" // or "postgresql"
196
- url = env("DATABASE_URL")
556
+ **RO-Crate Handler Example** (stream from database):
557
+
558
+ ```typescript
559
+ roCrateHandler: {
560
+ get: async (entity) => {
561
+ const jsonString = JSON.stringify(entity.rocrate, null, 2);
562
+
563
+ return {
564
+ type: 'stream',
565
+ stream: Readable.from([jsonString]),
566
+ metadata: {
567
+ contentType: 'application/ld+json',
568
+ contentLength: Buffer.byteLength(jsonString),
569
+ },
570
+ };
571
+ },
572
+ head: async (entity) => {
573
+ const jsonString = JSON.stringify(entity.rocrate);
574
+ return {
575
+ contentType: 'application/ld+json',
576
+ contentLength: Buffer.byteLength(jsonString),
577
+ };
578
+ },
197
579
  }
198
580
  ```
199
581
 
200
- ### 5. Generate Prisma Client and Run Migrations
582
+ ### File Handler Response Types
201
583
 
202
- ```bash
203
- # Generate the Prisma client
204
- npx prisma generate
584
+ The file handler must return one of two response types:
205
585
 
206
- # Apply database migrations
207
- npx prisma migrate deploy
586
+ **Redirect Response** - Redirect to external file location:
208
587
 
209
- # Or for development with migration creation
210
- npx prisma migrate dev
588
+ ```typescript
589
+ { type: 'redirect', url: 'https://storage.example.com/file.wav' }
211
590
  ```
212
591
 
213
- ## Available API Routes
592
+ **Stream Response** - Serve file content directly:
214
593
 
215
- The arocapi provides the following endpoints:
594
+ ```typescript
595
+ {
596
+ type: 'stream',
597
+ stream: Readable, // Node.js readable stream
598
+ metadata: {
599
+ contentType: 'audio/wav',
600
+ contentLength: 1024,
601
+ etag?: '"abc123"', // Optional
602
+ lastModified?: new Date(), // Optional
603
+ },
604
+ }
605
+ ```
216
606
 
217
- - `GET /entities` - List all entities with pagination and filtering
218
- - `GET /entity/:id` - Get a specific entity by ID
219
- - `POST /entity` - Create a new entity
220
- - `PUT /entity/:id` - Update an existing entity
221
- - `DELETE /entity/:id` - Delete an entity
222
- - `GET /search` - Search entities using OpenSearch
607
+ ### Query Parameters
608
+
609
+ The `/file/:id` endpoint supports these query parameters:
610
+
611
+ - `disposition` - 'inline' (default) or 'attachment' for download prompts
612
+ - `filename` - Custom filename for Content-Disposition header (defaults to entity.name)
613
+ - `noRedirect` - If true with redirect response, returns JSON `{location: url}` instead of HTTP 302
614
+
615
+ ### HTTP Range Support
616
+
617
+ The endpoint automatically handles HTTP range requests for partial content,
618
+ useful for media streaming:
619
+
620
+ - Returns **206 Partial Content** for valid range requests
621
+ - Returns **416 Range Not Satisfiable** for invalid ranges
622
+ - Sets appropriate `Content-Range` and `Accept-Ranges` headers
623
+
624
+ ### Entity Meta Field
625
+
626
+ The `meta` JSON field in the Entity model stores implementation-specific
627
+ metadata for your file handler:
628
+
629
+ ```typescript
630
+ await prisma.entity.create({
631
+ data: {
632
+ rocrateId: 'http://example.com/file/123',
633
+ name: 'audio.wav',
634
+ entityType: 'http://schema.org/MediaObject',
635
+ // ... other required fields
636
+ meta: {
637
+ bucket: 's3://my-bucket',
638
+ storagePath: 'collections/col-01',
639
+ checksum: 'sha256:abc123...',
640
+ },
641
+ },
642
+ });
643
+ ```
644
+
645
+ Your file handler can use this metadata to locate files in your storage system.
223
646
 
224
647
  ## Development Workflow
225
648
 
package/dist/app.d.ts CHANGED
@@ -1,10 +1,28 @@
1
1
  import type { Client } from '@opensearch-project/opensearch';
2
- import type { PrismaClient } from '@prisma/client/extension';
3
2
  import type { FastifyPluginAsync } from 'fastify';
3
+ import type { PrismaClient } from './generated/prisma/client.js';
4
+ import type { FileHandler, RoCrateHandler } from './types/fileHandlers.js';
5
+ import type { AccessTransformer, EntityTransformer, FileAccessTransformer, FileTransformer } from './types/transformers.js';
6
+ export type { AuthorisedEntity, AuthorisedFile, StandardEntity, StandardFile } from './transformers/default.js';
7
+ export { AllPublicAccessTransformer, AllPublicFileAccessTransformer } from './transformers/default.js';
8
+ export type { FileHandler, FileHandlerContext, FileMetadata, FilePathResult, FileRedirectResult, FileResult, FileStreamResult, GetFileHandler, GetRoCrateHandler, HeadFileHandler, HeadRoCrateHandler, RoCrateHandler, } from './types/fileHandlers.js';
9
+ export type { AccessTransformer, EntityTransformer, FileAccessTransformer, FileTransformer, TransformerContext, } from './types/transformers.js';
10
+ declare module 'fastify' {
11
+ interface FastifyInstance {
12
+ prisma: PrismaClient;
13
+ opensearch: Client;
14
+ }
15
+ }
4
16
  export type Options = {
5
17
  prisma: PrismaClient;
6
18
  opensearch: Client;
7
19
  disableCors?: boolean;
20
+ accessTransformer: AccessTransformer;
21
+ entityTransformers?: EntityTransformer[];
22
+ fileAccessTransformer: FileAccessTransformer;
23
+ fileTransformers?: FileTransformer[];
24
+ fileHandler: FileHandler;
25
+ roCrateHandler: RoCrateHandler;
8
26
  };
9
27
  declare const _default: FastifyPluginAsync<Options>;
10
28
  export default _default;
package/dist/app.js CHANGED
@@ -1,36 +1,23 @@
1
1
  import cors from '@fastify/cors';
2
2
  import sensible from '@fastify/sensible';
3
3
  import fp from 'fastify-plugin';
4
- import { hasZodFastifySchemaValidationErrors, isResponseSerializationError, serializerCompiler, validatorCompiler, } from 'fastify-type-provider-zod';
4
+ import { hasZodFastifySchemaValidationErrors, serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
5
+ import crate from './routes/crate.js';
5
6
  import entities from './routes/entities.js';
6
7
  import entity from './routes/entity.js';
8
+ import file from './routes/file.js';
9
+ import files from './routes/files.js';
7
10
  import search from './routes/search.js';
11
+ import { createValidationError } from './utils/errors.js';
12
+ export { AllPublicAccessTransformer, AllPublicFileAccessTransformer } from './transformers/default.js';
8
13
  const setupValidation = (fastify) => {
9
14
  fastify.setValidatorCompiler(validatorCompiler);
10
15
  fastify.setSerializerCompiler(serializerCompiler);
11
- fastify.setErrorHandler((err, req, reply) => {
12
- if (hasZodFastifySchemaValidationErrors(err)) {
13
- return reply.code(400).send({
14
- error: 'Response Validation Error',
15
- message: "Request doesn't match the schema",
16
- details: {
17
- issues: err.validation,
18
- method: req.method,
19
- url: req.url,
20
- },
21
- });
22
- }
23
- if (isResponseSerializationError(err)) {
24
- return reply.code(500).send({
25
- error: 'Internal Server Error',
26
- message: "Response doesn't match the schema",
27
- details: {
28
- issues: err.cause.issues,
29
- method: err.method,
30
- url: err.url,
31
- },
32
- });
16
+ fastify.setErrorHandler((error, _req, reply) => {
17
+ if (hasZodFastifySchemaValidationErrors(error)) {
18
+ return reply.code(400).send(createValidationError('The request parameters are invalid', error.validation));
33
19
  }
20
+ const err = error;
34
21
  return reply.code(500).send({
35
22
  error: 'Internal Server Error',
36
23
  message: err.message,
@@ -40,8 +27,8 @@ const setupValidation = (fastify) => {
40
27
  const setupDatabase = async (fastify, prisma) => {
41
28
  await prisma.$connect();
42
29
  fastify.decorate('prisma', prisma);
43
- fastify.addHook('onClose', async (server) => {
44
- await server.prisma.$disconnect();
30
+ fastify.addHook('onClose', async () => {
31
+ await prisma.$disconnect();
45
32
  });
46
33
  };
47
34
  const setupSearch = async (fastify, opensearch) => {
@@ -57,7 +44,25 @@ const setupSearch = async (fastify, opensearch) => {
57
44
  fastify.addHook('onClose', () => opensearch.close());
58
45
  };
59
46
  const app = async (fastify, options) => {
60
- const { prisma, opensearch, disableCors = false } = options || {};
47
+ const { prisma, opensearch, disableCors = false, accessTransformer, entityTransformers, fileAccessTransformer, fileTransformers, fileHandler, roCrateHandler, } = options;
48
+ if (!prisma) {
49
+ throw new Error('Prisma client is required');
50
+ }
51
+ if (!opensearch) {
52
+ throw new Error('OpenSearch client is required');
53
+ }
54
+ if (!accessTransformer) {
55
+ throw new Error('accessTransformer is required');
56
+ }
57
+ if (!fileAccessTransformer) {
58
+ throw new Error('fileAccessTransformer is required');
59
+ }
60
+ if (!fileHandler) {
61
+ throw new Error('fileHandler is required');
62
+ }
63
+ if (!roCrateHandler) {
64
+ throw new Error('roCrateHandler is required');
65
+ }
61
66
  fastify.register(sensible);
62
67
  if (!disableCors) {
63
68
  fastify.register(cors);
@@ -65,9 +70,12 @@ const app = async (fastify, options) => {
65
70
  setupValidation(fastify);
66
71
  await setupDatabase(fastify, prisma);
67
72
  await setupSearch(fastify, opensearch);
68
- fastify.register(entities);
69
- fastify.register(entity);
70
- fastify.register(search);
73
+ fastify.register(entities, { accessTransformer, entityTransformers });
74
+ fastify.register(entity, { accessTransformer, entityTransformers });
75
+ fastify.register(files, { fileAccessTransformer, fileTransformers });
76
+ fastify.register(file, { fileHandler });
77
+ fastify.register(crate, { roCrateHandler });
78
+ fastify.register(search, { accessTransformer, entityTransformers });
71
79
  };
72
80
  export default fp(app);
73
81
  //# sourceMappingURL=app.js.map