@epilot/cli 0.1.26 → 0.1.28

package/definitions/event-catalog.json

@@ -261,6 +261,118 @@
         }
       }
     },
+    "/v2/events/{event_name}:history": {
+      "post": {
+        "operationId": "searchEventHistoryV2",
+        "summary": "searchEventHistoryV2",
+        "description": "Paginated history of events with projected/lightweight payload (v2).\n\nReturns `EventSummary` objects instead of fully hydrated `Event` objects:\nnested entity graphs (objects/arrays-of-objects carrying `_schema`/`_id`)\nare stripped. Use GET /v2/events/{event_name}/history/{event_id} to fetch\nthe full hydrated event for a single result.\n",
+        "tags": [
+          "Event Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "event_name",
+            "in": "path",
+            "required": true,
+            "description": "Unique human readable name of the event",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SearchOptionsV2"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "List of event summaries in the event history",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/EventSummary"
+                      }
+                    },
+                    "next_cursor": {
+                      "type": "object",
+                      "description": "Cursor for pagination. Use this to get the next page of results.",
+                      "nullable": true,
+                      "properties": {
+                        "event_time": {
+                          "type": "string",
+                          "description": "Timestamp from the last event in the current page",
+                          "example": "2025-10-31T12:34:56Z"
+                        },
+                        "event_id": {
+                          "type": "string",
+                          "description": "Event ID from the last event in the current page",
+                          "example": "evt_1234567890abcdef"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v2/events/{event_name}/history/{event_id}": {
+      "get": {
+        "operationId": "getHistoricalEvent",
+        "summary": "getHistoricalEvent",
+        "description": "Fetch a single historical event by id with full hydration",
+        "tags": [
+          "Event Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "event_name",
+            "in": "path",
+            "required": true,
+            "description": "Unique human readable name of the event",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "event_id",
+            "in": "path",
+            "required": true,
+            "description": "Unique event identifier (ULID)",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The fully hydrated historical event",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Event"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Event not found"
+          }
+        }
+      }
+    },
     "/v1/events/{event_name}:trigger": {
       "post": {
         "operationId": "triggerEvent",
@@ -441,7 +553,7 @@
         ]
       },
       "UpdateEventPayload": {
-        "description": "Payload for updating an event configuration.\nAccepts the same fields as EventConfig (all optional for PATCH).\nCurrently only `enabled` and `auto_trigger` fields are processed, other fields are ignored.\n",
+        "description": "Payload for updating an event configuration.\nAccepts the same fields as EventConfig (all optional for PATCH).\nCurrently `enabled` and `auto_trigger` fields are processed.\n",
         "allOf": [
           {
             "$ref": "#/components/schemas/EventConfigBase"
@@ -495,6 +607,22 @@
           "entity_schema"
         ]
       },
+      "AttachmentField": {
+        "type": "object",
+        "description": "A schema field representing file attachments associated with the event.\nPresent in schema_fields for events tagged with \"attachment\".\n",
+        "properties": {
+          "items": {
+            "$ref": "#/components/schemas/EventAttachment"
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Whether this field is required in the event payload"
+          }
+        },
+        "required": [
+          "items"
+        ]
+      },
       "SchemaField": {
         "oneOf": [
           {
@@ -502,6 +630,9 @@
           },
           {
             "$ref": "#/components/schemas/ContextEntity"
+          },
+          {
+            "$ref": "#/components/schemas/AttachmentField"
           }
         ]
       },
@@ -764,6 +895,60 @@
           "contract_id": "880e8400-e29b-41d4-a716-446655440000"
         }
       },
+      "EventSummary": {
+        "type": "object",
+        "description": "A lightweight event summary returned by the v2 history endpoint.\n\nIncludes the standard `_*` metadata fields plus a projected subset of the\nevent payload. Hydrated entity objects (values carrying `_schema` or `_id`\nand arrays of such objects) are stripped — fetch via\n`GET /v2/events/{event_name}/history/{event_id}` for full hydration.\n\nProjected scalar payload fields appear as additional top-level properties.\n",
+        "properties": {
+          "_org_id": {
+            "type": "string",
+            "description": "epilot tenant/organization ID"
+          },
+          "_event_time": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp when event occurred"
+          },
+          "_event_id": {
+            "type": "string",
+            "description": "Unique event identifier (ULID)"
+          },
+          "_event_name": {
+            "type": "string",
+            "description": "Event name from catalog"
+          },
+          "_event_version": {
+            "type": "string",
+            "description": "Event version (semver)",
+            "example": "1.0.0"
+          },
+          "_event_source": {
+            "type": "string",
+            "description": "Source that triggered the event"
+          },
+          "_trigger_source_type": {
+            "type": "string",
+            "description": "The type of system that triggered the event.\nCommon values: api, automation, operation, portal_user\n",
+            "example": "api"
+          },
+          "_trigger_source": {
+            "type": "string",
+            "description": "Identifier of the specific trigger source.\n"
+          },
+          "_ack_id": {
+            "type": "string",
+            "description": "Unique acknowledgment tracking ID for the event.\n"
+          }
+        },
+        "required": [
+          "_org_id",
+          "_event_time",
+          "_event_id",
+          "_event_name",
+          "_event_version",
+          "_event_source"
+        ],
+        "additionalProperties": true
+      },
       "GraphDefinition": {
         "type": "object",
         "description": "Entity graph definition for resolving related entities",
@@ -959,6 +1144,22 @@
           }
         }
       },
+      "SearchOptionsV2": {
+        "description": "Search options for the v2 history endpoint.\n\nExtends `SearchOptions` with an optional `fields` projection. When `fields`\nis omitted, the response includes all `_*` metadata plus all scalar payload\nfields (and primitive arrays / empty objects/arrays) after entity stripping.\nWhen `fields` is provided, glob/exclusion semantics from `FieldsParam` apply\nagainst `payload.*` paths; `_*` metadata is always included. Entity stripping\nruns AFTER selection.\n",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/SearchOptions"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "fields": {
+                "$ref": "#/components/schemas/FieldsParam"
+              }
+            }
+          }
+        ]
+      },
       "FieldsParam": {
         "type": "array",
         "description": "List of entity fields to include or exclude in the response\n\nUse ! to exclude fields, e.g. `!_id` to exclude the `_id` field.\n\nGlobbing and globstart (**) is supported for nested fields.\n",
@@ -1040,6 +1241,60 @@
           "success",
           "event_id"
         ]
+      },
+      "EventAttachment": {
+        "type": "object",
+        "description": "A file attachment associated with an event",
+        "properties": {
+          "entity_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Entity ID of the file"
+          },
+          "filename": {
+            "type": "string",
+            "description": "Name of the file"
+          },
+          "mime_type": {
+            "type": "string",
+            "description": "MIME type of the file (e.g., application/pdf)"
+          },
+          "size_bytes": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "File size in bytes"
+          },
+          "s3ref": {
+            "type": "object",
+            "description": "S3 reference for the file content",
+            "properties": {
+              "bucket": {
+                "type": "string",
+                "description": "S3 bucket name"
+              },
+              "key": {
+                "type": "string",
+                "description": "S3 object key"
+              }
+            },
+            "required": [
+              "bucket",
+              "key"
+            ]
+          },
+          "version_index": {
+            "type": "integer",
+            "description": "File version index (always 0 for newly created files)"
+          },
+          "readable_size": {
+            "type": "string",
+            "description": "Human-readable file size (e.g., \"200 KB\")"
+          }
+        },
+        "required": [
+          "entity_id",
+          "version_index"
+        ]
       }
     }
   },

package/definitions/file.json

@@ -780,6 +780,101 @@
         }
       }
     },
+    "/v1/files:zipJob": {
+      "post": {
+        "operationId": "createZipJob",
+        "summary": "createZipJob",
+        "description": "Create a background job to ZIP multiple files and send a download link via email.\n\nFor bulk downloads of more than 50 files, use this async endpoint instead of client-side zipping.\nThe job will:\n1. Download all requested files from S3\n2. Create a ZIP archive\n3. Upload the ZIP to temporary storage\n4. Send an email notification with the download link\n\nThe ZIP file will be available for 7 days.\n",
+        "tags": [
+          "File"
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateZipJobPayload"
+              },
+              "examples": {
+                "Zip multiple files": {
+                  "value": {
+                    "file_entity_ids": [
+                      "ef7d985c-2385-44f4-9c71-ae06a52264f8",
+                      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+                    ],
+                    "zip_filename": "Documents.zip",
+                    "notify_email": true
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Job created, processing in background",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ZipJob"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequestError"
+          },
+          "401": {
+            "$ref": "#/components/responses/UnauthorizedError"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v1/files:zipJob/{job_id}": {
+      "get": {
+        "operationId": "getZipJob",
+        "summary": "getZipJob",
+        "description": "Get the status of a ZIP job",
+        "tags": [
+          "File"
+        ],
+        "parameters": [
+          {
+            "name": "job_id",
+            "in": "path",
+            "required": true,
+            "description": "The UUID of the ZIP job",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ZIP job status",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ZipJob"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/UnauthorizedError"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFoundError"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v1/files/{id}/preview": {
       "get": {
         "operationId": "previewFile",
@@ -1199,8 +1294,7 @@
       "get": {
         "operationId": "listPublicLinksForFile",
         "summary": "listPublicLinksForFile",
-        "description": "**Not yet implemented.**\n\nThis endpoint will fetch all public links previously generated for a file.\n",
-        "x-not-implemented": true,
+        "description": "Fetches all public links previously generated for a file",
         "parameters": [
           {
             "name": "id",
@@ -1340,8 +1434,7 @@
       "delete": {
         "operationId": "revokePublicLink",
         "summary": "revokePublicLink",
-        "description": "**Not yet implemented.**\n\nThis endpoint will revoke a public link, making the file inaccessible via that link.\n",
-        "x-not-implemented": true,
+        "description": "Revokes a given public link by ID",
         "parameters": [
           {
             "name": "id",
@@ -2378,6 +2471,171 @@
           ]
         }
       },
+      "CreateZipJobPayload": {
+        "type": "object",
+        "description": "Request payload to create a ZIP job for bulk file download.\nProvide either an explicit list of `file_entity_ids` (up to 1000) or an\n`entity_query` that resolves to file entities (up to 10000).\n",
+        "properties": {
+          "file_entity_ids": {
+            "type": "array",
+            "description": "List of file entity IDs to include in the ZIP",
+            "items": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "minItems": 1,
+            "maxItems": 1000,
+            "example": [
+              "ef7d985c-2385-44f4-9c71-ae06a52264f8",
+              "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+            ]
+          },
+          "entity_query": {
+            "type": "object",
+            "description": "Entity search query used to resolve files to include in the ZIP",
+            "properties": {
+              "q": {
+                "type": "string",
+                "description": "Lucene-style search query (same syntax as entity search)",
+                "example": "_schema:file AND _tags:invoice"
+              },
+              "sort": {
+                "type": "string",
+                "description": "Sort expression forwarded to the entity search",
+                "example": "_created_at:desc"
+              }
+            },
+            "required": [
+              "q"
+            ]
+          },
+          "zip_filename": {
+            "type": "string",
+            "description": "Name of the generated ZIP file",
+            "default": "Files.zip",
+            "example": "Documents.zip"
+          },
+          "notify_email": {
+            "type": "boolean",
+            "description": "Send email notification when ZIP is ready",
+            "default": true
+          }
+        },
+        "oneOf": [
+          {
+            "required": [
+              "file_entity_ids"
+            ]
+          },
+          {
+            "required": [
+              "entity_query"
+            ]
+          }
+        ]
+      },
+      "ZipJob": {
+        "type": "object",
+        "description": "ZIP job status and result",
+        "properties": {
+          "job_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique identifier for the ZIP job",
+            "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+          },
+          "status": {
+            "type": "string",
+            "description": "Current status of the ZIP job",
+            "enum": [
+              "queued",
+              "downloading",
+              "zipping",
+              "uploading",
+              "sending_notification",
+              "completed",
+              "failed"
+            ],
+            "example": "completed"
+          },
+          "progress": {
+            "type": "object",
+            "description": "Progress information for the job",
+            "properties": {
+              "total_files": {
+                "type": "integer",
+                "description": "Total number of files to process",
+                "example": 100
+              },
+              "downloaded_files": {
+                "type": "integer",
+                "description": "Number of files successfully downloaded",
+                "example": 75
+              },
+              "failed_files": {
+                "type": "integer",
+                "description": "Number of files that failed to download",
+                "example": 2
+              }
+            }
+          },
+          "result": {
+            "type": "object",
+            "description": "Result of the completed ZIP job",
+            "properties": {
+              "file_entity_id": {
+                "type": "string",
+                "format": "uuid",
+                "description": "File entity ID of the generated ZIP",
+                "example": "ef7d985c-2385-44f4-9c71-ae06a52264f8"
+              },
+              "download_url": {
+                "type": "string",
+                "format": "uri",
+                "description": "Presigned download URL (expires in 24 hours)",
+                "example": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/files.zip?X-Amz-..."
+              },
+              "expires_at": {
+                "type": "string",
+                "format": "date-time",
+                "description": "When the download URL expires",
+                "example": "2024-01-02T12:00:00Z"
+              },
+              "zip_size_bytes": {
+                "type": "integer",
+                "description": "Size of the generated ZIP file in bytes",
+                "example": 104857600
+              }
+            }
+          },
+          "error": {
+            "type": "string",
+            "description": "Error message if job failed",
+            "example": "Failed to download file: access denied"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the job was created",
+            "example": "2024-01-01T12:00:00Z"
+          },
+          "created_by": {
+            "type": "string",
+            "description": "User ID who created the job",
+            "example": "10234"
+          },
+          "org_id": {
+            "type": "string",
+            "description": "Organization ID",
+            "example": "123"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the job was last updated",
+            "example": "2024-01-01T12:05:00Z"
+          }
+        }
+      },
       "VerifyCustomDownloadUrlPayload": {
         "type": "object",
         "properties": {