Codex fixes

Author: MilanKomsa

packages/plugin-epcis/docs/EPCIS-Integration-Guide.md

@@ -573,7 +573,12 @@ Accept an EPCIS Document and queue it for publishing to DKG.
 }
 ```
 
-**Response** (HTTP 202 Accepted):
+**Response modes:**
+
+- **HTTP 202 Accepted**: Capture queued in publisher (numeric `captureID`, status is queryable)
+- **HTTP 201 Created**: Publisher unavailable, fallback published directly to DKG (`captureID` in `direct-*` format, includes `UAL`)
+
+**Example (HTTP 202 Accepted):**
 
 ```json
 {
@@ -584,11 +589,27 @@ Accept an EPCIS Document and queue it for publishing to DKG.
 }
 ```
 
+**Example (HTTP 201 Created - direct fallback):**
+
+```json
+{
+  "status": "201",
+  "receivedAt": "2024-03-01T08:00:01.123Z",
+  "captureID": "direct-1709280001123",
+  "eventCount": 1,
+  "UAL": "did:dkg:otp/0x1234.../789"
+}
+```
+
 ---
 
 ### GET `/epcis/capture/:captureID`
 
-Check the status of a previously submitted capture.
+Check the status of a previously submitted capture tracked by the publisher.
+
+> **Note:** This endpoint accepts numeric publisher `captureID` values.  
+> Direct fallback IDs (`direct-*`) are not tracked by publisher status API.  
+> For fallback captures, use the returned `UAL` with `GET /epcis/asset/*ual`.
 
 **Response:**
 
@@ -623,13 +644,13 @@ Query EPCIS events from the DKG.
 | `to` | string (ISO 8601) | End of time range | `2024-03-31T23:59:59Z` |
 | `bizStep` | string | Filter by business step | `assembling` or full URI |
 | `bizLocation` | string | Filter by location | `urn:epc:id:sgln:4012345.00002.0` |
-| `fullTrace` | string | Search all EPC fields | `true` |
+| `fullTrace` | string enum | Must be `"true"` or `"false"` | `true` |
 | `parentID` | string | Filter by parent EPC (AggregationEvent) | `urn:epc:id:sscc:...` |
 | `childEPC` | string | Filter by child EPC (AggregationEvent) | `urn:epc:id:sgtin:...` |
 | `inputEPC` | string | Filter by input EPC (TransformationEvent) | `urn:epc:id:sgtin:...` |
 | `outputEPC` | string | Filter by output EPC (TransformationEvent) | `urn:epc:id:sgtin:...` |
-| `limit` | number | Results per page (default: 100, max: 1000) | `50` |
-| `offset` | number | Results to skip (pagination) | `0` |
+| `limit` | integer | Results per page (default: 100, range: 1-1000) | `50` |
+| `offset` | integer | Results to skip (pagination, min: 0) | `0` |
 
 **Response:**
 

packages/plugin-epcis/src/index.ts

@@ -5,7 +5,7 @@ import { EpcisQueryService } from "./services/EPCISQueryService";
 import { formatSourceKAs } from "./utils/sourceKA";
 import type { CaptureResponse } from "./model/types";
 
-// Timeout for internal publisher requests (30s for POST, 5s for GET)
+// Timeout for internal publisher requests (10s for POST, 5s for GET)
 const PUBLISHER_POST_TIMEOUT_MS = 10000;
 const PUBLISHER_GET_TIMEOUT_MS = 5000;
 
@@ -368,10 +368,12 @@ export default defineDkgPlugin((ctx, mcp, api) => {
       {
         tag: "EPCIS",
         summary: "Get Capture Status",
-        description: "Check the status of an EPCIS capture by captureID",
+        description:
+          "Check publisher-tracked status by numeric captureID. " +
+          "Direct fallback IDs (direct-*) are published directly to DKG and are not tracked by this endpoint.",
         params: z.object({
           captureID: z.string().openapi({
-            description: "The capture ID returned from POST /epcis/capture",
+            description: "Numeric publisher capture ID returned from POST /epcis/capture",
             example: "123",
           }),
         }),
@@ -392,6 +394,16 @@ export default defineDkgPlugin((ctx, mcp, api) => {
           const publisherUrl = process.env.PUBLISHER_URL || "http://localhost:9200";
 
           const captureIdPattern = /^[0-9]{1,20}$/;
+          const directCaptureIdPattern = /^direct-[0-9]+$/;
+
+          if (directCaptureIdPattern.test(captureID)) {
+            return res.status(400).json({
+              error: "Direct fallback capture IDs are not tracked by publisher status API",
+              message: "This capture was published directly to DKG. Use the returned UAL to retrieve the asset.",
+              captureID,
+            } as any);
+          }
+
           if (!captureIdPattern.test(captureID)) {
             return res.status(400).json({
               error: "Invalid captureID format",
@@ -474,7 +486,7 @@ export default defineDkgPlugin((ctx, mcp, api) => {
             description: "Filter by business location",
             example: "urn:epc:id:sgln:0614141.00001.0",
           }),
-          fullTrace: z.string().optional().openapi({
+          fullTrace: z.enum(["true", "false"]).optional().openapi({
             description: "If 'true', search all EPC fields for full supply chain traceability",
             example: "true",
           }),
@@ -531,6 +543,26 @@ export default defineDkgPlugin((ctx, mcp, api) => {
             }
           }
 
+          // Parse + validate pagination params
+          const parsedLimit =
+            typeof limit === "string" && limit.length > 0 ? Number.parseInt(limit, 10) : undefined;
+          const parsedOffset =
+            typeof offset === "string" && offset.length > 0 ? Number.parseInt(offset, 10) : undefined;
+
+          if (parsedLimit !== undefined && (!Number.isInteger(parsedLimit) || parsedLimit < 1 || parsedLimit > 1000)) {
+            return res.status(400).json({
+              success: false,
+              error: "Parameter 'limit' must be an integer between 1 and 1000",
+            } as any);
+          }
+
+          if (parsedOffset !== undefined && (!Number.isInteger(parsedOffset) || parsedOffset < 0)) {
+            return res.status(400).json({
+              success: false,
+              error: "Parameter 'offset' must be a non-negative integer",
+            } as any);
+          }
+
           // Build the SPARQL query based on parameters
           const sparqlQuery = queryService.buildQuery({
             epc: epc as string,
@@ -543,8 +575,8 @@ export default defineDkgPlugin((ctx, mcp, api) => {
             childEPC: childEPC as string,
             inputEPC: inputEPC as string,
             outputEPC: outputEPC as string,
-            limit: limit ? parseInt(limit as string, 10) : undefined,
-            offset: offset ? parseInt(offset as string, 10) : undefined,
+            limit: parsedLimit,
+            offset: parsedOffset,
           });
 
           console.log("[EPCIS Events] Executing SPARQL query:", sparqlQuery);
@@ -553,13 +585,13 @@ export default defineDkgPlugin((ctx, mcp, api) => {
           const results = await ctx.dkg.graph.query(sparqlQuery, "SELECT");
 
           // Calculate pagination values
-          const effectiveLimit = Math.min(limit ? parseInt(limit as string, 10) : 100, 1000);
-          const effectiveOffset = offset ? parseInt(offset as string, 10) : 0;
-          const resultCount = results?.length || 0;
+          const effectiveLimit = parsedLimit ?? 100;
+          const effectiveOffset = parsedOffset ?? 0;
+          const resultCount = results?.data?.length || 0;
 
           res.json({
             success: true,
-            results: results || [],
+            results: results?.data || [],
             count: resultCount,
             pagination: {
               limit: effectiveLimit,