From fd37bff25049dde1bd3bede66d89cb406d79c4c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 08:54:22 +0000 Subject: [PATCH] chore(automation-client): add searchExecutions with cursor pagination Update the automation client spec with the new POST /v1/automation/executions:search endpoint (cursor-based pagination of an entity's executions) and bump to 2.34.0. Co-authored-by: Claude --- .../automation-client-search-executions.md | 5 + clients/automation-client/package.json | 2 +- .../src/openapi-runtime.json | 12 ++ clients/automation-client/src/openapi.d.ts | 137 ++++++++++++++++- clients/automation-client/src/openapi.json | 140 +++++++++++++++++- 5 files changed, 293 insertions(+), 3 deletions(-) create mode 100644 .changeset/automation-client-search-executions.md diff --git a/.changeset/automation-client-search-executions.md b/.changeset/automation-client-search-executions.md new file mode 100644 index 00000000..9c14844c --- /dev/null +++ b/.changeset/automation-client-search-executions.md @@ -0,0 +1,5 @@ +--- +"@epilot/automation-client": minor +--- + +Add `searchExecutions` operation (`POST /v1/automation/executions:search`) — cursor-based pagination for an entity's automation executions (`size`, `cursor` body params, `next_cursor` in the response) diff --git a/clients/automation-client/package.json b/clients/automation-client/package.json index 8a899f0b..64fb50fa 100644 --- a/clients/automation-client/package.json +++ b/clients/automation-client/package.json @@ -1,6 +1,6 @@ { "name": "@epilot/automation-client", - "version": "2.33.4", + "version": "2.34.0", "description": "Client library for epilot automation API", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/clients/automation-client/src/openapi-runtime.json b/clients/automation-client/src/openapi-runtime.json index 1d44a511..378153e7 100644 --- a/clients/automation-client/src/openapi-runtime.json +++ b/clients/automation-client/src/openapi-runtime.json @@ -130,6 +130,18 @@ "responses": {} } }, + "/v1/automation/executions:search": { + "post": { + "operationId": "searchExecutions", + "requestBody": { + "required": true, + "content": { + "application/json": {} + } + }, + "responses": {} + } + }, "/v1/automation/executions/bulk-jobs": { "post": { "operationId": "bulkTriggerExecutions", diff --git a/clients/automation-client/src/openapi.d.ts b/clients/automation-client/src/openapi.d.ts index f0110bf6..d265a5de 100644 --- a/clients/automation-client/src/openapi.d.ts +++ b/clients/automation-client/src/openapi.d.ts @@ -720,9 +720,64 @@ declare namespace Components { */ remove?: string[]; /** - * Assignees to add to the thread + * Assignees to add to the thread. For even_distribution this may contain group IDs (prefixed "group_") whose members are candidates. */ add?: string[]; + /** + * How assignees in `add` are resolved. + * - direct: assign exactly the users in `add` (default). + * - even_distribution: treat `add` as a candidate pool (users and/or groups) + * and assign the least-loaded available agent. + * - sequential: reserved for future use. + * + */ + assignment_type?: "direct" | "even_distribution" | "sequential"; + /** + * Candidate condition for even_distribution: when true, skip users who + * are currently absent (out-of-office). Opt-in; defaults to false. + * + */ + only_available_users?: boolean; + /** + * Candidate condition for even_distribution: when true, only assign to + * users whose skills (tags) match a label on the message. Opt-in; + * defaults to false. + * + */ + match_user_skills?: boolean; + /** + * Candidate condition (with match_user_skills): label families + * (taxonomy slugs) that must match. A user qualifies only if it shares + * a label with the message within each of these categories. Leave empty + * to match on any label (flat OR across all categories). + * + */ + required_skill_categories?: string[]; + /** + * How strictly required skill categories are matched (applies with + * match_user_skills and required skill categories set). + * - require_all: hard match (default) — a user must match every required + * category the message has a label in. + * - prefer: soft match — prefer the best-matching users, relaxing to + * fewer categories only when no better match exists; a user matching + * no category is never eligible (the fallback then applies). + * + */ + skill_match_mode?: "require_all" | "prefer"; + /** + * What to do when smart assignment resolves no assignable candidate. + * Applies to even_distribution. + * - leave_unassigned: leave the thread unassigned (default). + * - assign_to_fallback: route to the users/groups in `fallback_assignees`. + * + */ + fallback?: "leave_unassigned" | "assign_to_fallback"; + /** + * Target user/group IDs (group IDs prefixed "group_") to assign when + * `fallback` is "assign_to_fallback". + * + */ + fallback_assignees?: string[]; } /** * example: @@ -3596,6 +3651,40 @@ declare namespace Components { total: number; results: AutomationFlow[]; } + export interface SearchExecutionsReq { + entity_id: /** + * example: + * e3d3ebac-baab-4395-abf4-50b5bf1f8b74 + */ + EntityId; + /** + * Include flow automations in the response + */ + include_flows?: boolean; + /** + * Max number of executions to return per page + */ + size?: number; + /** + * Opaque cursor returned as next_cursor by a previous page. + * Pass it to fetch the next page of results. + * + */ + cursor?: string; + } + export interface SearchExecutionsResp { + /** + * Number of executions in this page + */ + total: number; + results: AutomationExecution[]; + /** + * Opaque cursor to fetch the next page of results. + * Only present when more results are available. + * + */ + next_cursor?: string; + } export interface SendEmailAction { id?: /** * example: @@ -5046,6 +5135,20 @@ declare namespace Paths { Components.Responses.NotFoundError; } } + namespace SearchExecutions { + export type RequestBody = Components.Schemas.SearchExecutionsReq; + namespace Responses { + export type $200 = Components.Schemas.SearchExecutionsResp; + export type $403 = /** + * example: + * { + * "status": 403, + * "error": "Forbidden" + * } + */ + Components.Responses.ForbiddenError; + } + } namespace SearchFlows { namespace Parameters { export type From = number; @@ -5189,6 +5292,20 @@ export interface OperationMethods { data?: Paths.StartExecution.RequestBody, config?: AxiosRequestConfig ): OperationResponse + /** + * searchExecutions - searchExecutions + * + * Search automation executions of an entity with cursor-based pagination. + * Returns pages of up to 100 executions, newest first. + * Prefer this over GET /v1/automation/executions, which returns the full + * execution history in a single response. + * + */ + 'searchExecutions'( + parameters?: Parameters | null, + data?: Paths.SearchExecutions.RequestBody, + config?: AxiosRequestConfig + ): OperationResponse /** * bulkTriggerExecutions - bulkTriggerExecutions * @@ -5365,6 +5482,22 @@ export interface PathsDictionary { config?: AxiosRequestConfig ): OperationResponse } + ['/v1/automation/executions:search']: { + /** + * searchExecutions - searchExecutions + * + * Search automation executions of an entity with cursor-based pagination. + * Returns pages of up to 100 executions, newest first. + * Prefer this over GET /v1/automation/executions, which returns the full + * execution history in a single response. + * + */ + 'post'( + parameters?: Parameters | null, + data?: Paths.SearchExecutions.RequestBody, + config?: AxiosRequestConfig + ): OperationResponse + } ['/v1/automation/executions/bulk-jobs']: { /** * bulkTriggerExecutions - bulkTriggerExecutions @@ -5572,6 +5705,8 @@ export type ResumeToken = Components.Schemas.ResumeToken; export type RetryReq = Components.Schemas.RetryReq; export type RetryStrategy = Components.Schemas.RetryStrategy; export type SearchAutomationsResp = Components.Schemas.SearchAutomationsResp; +export type SearchExecutionsReq = Components.Schemas.SearchExecutionsReq; +export type SearchExecutionsResp = Components.Schemas.SearchExecutionsResp; export type SendEmailAction = Components.Schemas.SendEmailAction; export type SendEmailActionConfig = Components.Schemas.SendEmailActionConfig; export type SendEmailCondition = Components.Schemas.SendEmailCondition; diff --git a/clients/automation-client/src/openapi.json b/clients/automation-client/src/openapi.json index eebb2120..f2ae613c 100644 --- a/clients/automation-client/src/openapi.json +++ b/clients/automation-client/src/openapi.json @@ -621,6 +621,42 @@ } } }, + "/v1/automation/executions:search": { + "post": { + "operationId": "searchExecutions", + "summary": "searchExecutions", + "description": "Search automation executions of an entity with cursor-based pagination.\nReturns pages of up to 100 executions, newest first.\nPrefer this over GET /v1/automation/executions, which returns the full\nexecution history in a single response.\n", + "tags": [ + "executions" + ], + "requestBody": { + "description": "Search parameters", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchExecutionsReq" + } + } + } + }, + "responses": { + "200": { + "description": "A page of automation executions", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchExecutionsResp" + } + } + } + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + } + } + } + }, "/v1/automation/executions/bulk-jobs": { "post": { "operationId": "bulkTriggerExecutions", @@ -2187,7 +2223,59 @@ }, "add": { "type": "array", - "description": "Assignees to add to the thread", + "description": "Assignees to add to the thread. For even_distribution this may contain group IDs (prefixed \"group_\") whose members are candidates.", + "items": { + "type": "string" + } + }, + "assignment_type": { + "type": "string", + "description": "How assignees in `add` are resolved.\n- direct: assign exactly the users in `add` (default).\n- even_distribution: treat `add` as a candidate pool (users and/or groups)\n and assign the least-loaded available agent.\n- sequential: reserved for future use.\n", + "enum": [ + "direct", + "even_distribution", + "sequential" + ], + "default": "direct" + }, + "only_available_users": { + "type": "boolean", + "description": "Candidate condition for even_distribution: when true, skip users who\nare currently absent (out-of-office). Opt-in; defaults to false.\n", + "default": false + }, + "match_user_skills": { + "type": "boolean", + "description": "Candidate condition for even_distribution: when true, only assign to\nusers whose skills (tags) match a label on the message. Opt-in;\ndefaults to false.\n", + "default": false + }, + "required_skill_categories": { + "type": "array", + "description": "Candidate condition (with match_user_skills): label families\n(taxonomy slugs) that must match. A user qualifies only if it shares\na label with the message within each of these categories. Leave empty\nto match on any label (flat OR across all categories).\n", + "items": { + "type": "string" + } + }, + "skill_match_mode": { + "type": "string", + "description": "How strictly required skill categories are matched (applies with\nmatch_user_skills and required skill categories set).\n- require_all: hard match (default) — a user must match every required\n category the message has a label in.\n- prefer: soft match — prefer the best-matching users, relaxing to\n fewer categories only when no better match exists; a user matching\n no category is never eligible (the fallback then applies).\n", + "enum": [ + "require_all", + "prefer" + ], + "default": "require_all" + }, + "fallback": { + "type": "string", + "description": "What to do when smart assignment resolves no assignable candidate.\nApplies to even_distribution.\n- leave_unassigned: leave the thread unassigned (default).\n- assign_to_fallback: route to the users/groups in `fallback_assignees`.\n", + "enum": [ + "leave_unassigned", + "assign_to_fallback" + ], + "default": "leave_unassigned" + }, + "fallback_assignees": { + "type": "array", + "description": "Target user/group IDs (group IDs prefixed \"group_\") to assign when\n`fallback` is \"assign_to_fallback\".\n", "items": { "type": "string" } @@ -3885,6 +3973,56 @@ "results" ] }, + "SearchExecutionsReq": { + "type": "object", + "properties": { + "entity_id": { + "$ref": "#/components/schemas/EntityId" + }, + "include_flows": { + "description": "Include flow automations in the response", + "type": "boolean", + "default": false + }, + "size": { + "description": "Max number of executions to return per page", + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 25 + }, + "cursor": { + "description": "Opaque cursor returned as next_cursor by a previous page.\nPass it to fetch the next page of results.\n", + "type": "string" + } + }, + "required": [ + "entity_id" + ] + }, + "SearchExecutionsResp": { + "type": "object", + "properties": { + "total": { + "description": "Number of executions in this page", + "type": "number" + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AutomationExecution" + } + }, + "next_cursor": { + "description": "Opaque cursor to fetch the next page of results.\nOnly present when more results are available.\n", + "type": "string" + } + }, + "required": [ + "total", + "results" + ] + }, "StartExecutionRequest": { "type": "object", "properties": {