@epilot/sdk 2.8.0-rc.0 → 2.8.1

package/definitions/focus-pocus.json

@@ -1,757 +0,0 @@
-{
-  "openapi": "3.0.3",
-  "info": {
-    "title": "Focus Pocus API",
-    "description": "Backend service powering the achievements and mascot features in the epilot 360 portal.\nTracks user activity, evaluates achievement criteria, awards XP, and exposes the\nunified achievements feed and active challenge state.\n",
-    "version": "0.2.0",
-    "contact": {
-      "name": "epilot",
-      "email": "info@epilot.cloud",
-      "url": "https://epilot.cloud"
-    }
-  },
-  "servers": [
-    {
-      "url": "https://focus-pocus.dev.sls.epilot.io"
-    },
-    {
-      "url": "https://focus-pocus.staging.sls.epilot.io",
-      "description": "staging"
-    },
-    {
-      "url": "https://focus-pocus.sls.epilot.io",
-      "description": "prod"
-    }
-  ],
-  "security": [
-    {
-      "EpilotAuth": []
-    }
-  ],
-  "paths": {
-    "/v1/health": {
-      "get": {
-        "operationId": "getHealth",
-        "summary": "getHealth",
-        "description": "Liveness probe for the Focus Pocus API. Requires a valid EpilotAuth token.",
-        "tags": [
-          "Health"
-        ],
-        "responses": {
-          "200": {
-            "description": "Service is healthy.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/HealthResponse"
-                }
-              }
-            }
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          }
-        }
-      }
-    },
-    "/v1/achievements": {
-      "get": {
-        "operationId": "listAchievements",
-        "summary": "listAchievements",
-        "description": "Unified feed for the authenticated user: returns active challenges and completed\nv1 static achievement unlocks. The `userId` is read from the EpilotAuth claim —\nno user path or query parameter is accepted. Active challenges appear first,\nfollowed by completed items sorted by `unlocked_at` descending.\nItems unlocked within the last 60 seconds have `just_unlocked: true`.\n",
-        "tags": [
-          "Achievements"
-        ],
-        "responses": {
-          "200": {
-            "description": "Unified achievements feed for the authenticated user.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/AchievementFeedListResponse"
-                }
-              }
-            }
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          }
-        }
-      }
-    },
-    "/v1/achievements/{id}": {
-      "get": {
-        "operationId": "getAchievement",
-        "summary": "getAchievement",
-        "description": "Single user-scoped achievement or active-challenge item. Returns 404 if the id\ndoes not belong to the authenticated user.\n",
-        "tags": [
-          "Achievements"
-        ],
-        "parameters": [
-          {
-            "$ref": "#/components/parameters/AchievementOrChallengeId"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "User-scoped achievement or challenge feed item.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/AchievementFeedItem"
-                }
-              }
-            }
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
-          }
-        }
-      }
-    },
-    "/v1/challenges/suggest": {
-      "get": {
-        "operationId": "getSuggestedChallenge",
-        "summary": "getSuggestedChallenge",
-        "description": "Returns a suggested challenge for the authenticated user. The suggestion is\npersisted with a 7-day TTL. Calling again with the same `(user, category)`\nwithin 24h returns the existing suggestion without creating a new row.\nReturns 204 when all candidate templates have been dismissed within the last 24h.\n",
-        "tags": [
-          "Challenges"
-        ],
-        "parameters": [
-          {
-            "name": "route",
-            "in": "query",
-            "required": false,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Current frontend route (page context for suggestion selection)."
-          },
-          {
-            "name": "entity_type",
-            "in": "query",
-            "required": false,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Entity type currently in view (e.g. contact, opportunity)."
-          },
-          {
-            "name": "category_hint",
-            "in": "query",
-            "required": false,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Caller hint for preferred challenge category."
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Suggested challenge for the authenticated user.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ChallengeSuggested"
-                }
-              }
-            }
-          },
-          "204": {
-            "description": "No suitable challenge available (all candidates dismissed within 24h)."
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "500": {
-            "description": "Internal server error.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/v1/challenges/{id}/accept": {
-      "post": {
-        "operationId": "acceptChallenge",
-        "summary": "acceptChallenge",
-        "description": "Accept a suggested challenge. Atomically transitions the challenge from\n`suggested` to `active` using a conditional DynamoDB UpdateItem. Returns 409 if\nthe challenge has already been transitioned or the user already has\nMAX_ACTIVE_CHALLENGES (3) active challenges.\n",
-        "tags": [
-          "Challenges"
-        ],
-        "parameters": [
-          {
-            "$ref": "#/components/parameters/ChallengeId"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Challenge accepted and now active.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ChallengeActive"
-                }
-              }
-            }
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
-          },
-          "409": {
-            "$ref": "#/components/responses/Conflict"
-          }
-        }
-      }
-    },
-    "/v1/challenges/{id}/dismiss": {
-      "post": {
-        "operationId": "dismissChallenge",
-        "summary": "dismissChallenge",
-        "description": "Dismiss a suggested challenge. Atomically transitions the challenge from\n`suggested` to `dismissed`. The challenge template is filtered from `/suggest`\nresponses for the next 24h. Returns 409 if the challenge has already been\ntransitioned (e.g. already accepted or dismissed).\n",
-        "tags": [
-          "Challenges"
-        ],
-        "parameters": [
-          {
-            "$ref": "#/components/parameters/ChallengeId"
-          }
-        ],
-        "responses": {
-          "204": {
-            "description": "Challenge dismissed."
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
-          },
-          "409": {
-            "$ref": "#/components/responses/Conflict"
-          }
-        }
-      }
-    },
-    "/v1/challenges/active": {
-      "get": {
-        "operationId": "listActiveChallenges",
-        "summary": "listActiveChallenges",
-        "description": "Returns all active challenges for the authenticated user. Challenges whose\ndeadline has passed are lazily expired (fire-and-forget UpdateItem) and\nexcluded from the response. The result set is bounded by MAX_ACTIVE_CHALLENGES=3.\n",
-        "tags": [
-          "Challenges"
-        ],
-        "responses": {
-          "200": {
-            "description": "Active challenges for the authenticated user.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ActiveChallengeListResponse"
-                }
-              }
-            }
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          }
-        }
-      }
-    },
-    "/v1/events": {
-      "post": {
-        "operationId": "postEvent",
-        "summary": "postEvent",
-        "description": "Persist-first event ingest. Accepts an activity event, writes it to the event log\nidempotently (keyed by `event_id`), and returns 202. Achievement evaluation happens\nasynchronously — no unlocks are returned in the response.\n",
-        "tags": [
-          "Events"
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/EventIngestRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "Event accepted for async evaluation.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/EventAccepted"
-                }
-              }
-            }
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          }
-        }
-      }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "EpilotAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT",
-        "description": "epilot JWT bearer token issued by the platform Lambda authorizer."
-      }
-    },
-    "parameters": {
-      "AchievementId": {
-        "name": "id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "pattern": "^[a-z0-9][a-z0-9_-]{0,127}$"
-        }
-      },
-      "AchievementOrChallengeId": {
-        "name": "id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 128
-        },
-        "description": "Achievement id (lowercase slug) or challenge UUID. Accepts both formats because\nchallenge ids are UUIDs (uppercase hex) which the AchievementId slug pattern rejects.\n"
-      },
-      "ChallengeId": {
-        "name": "id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 128
-        },
-        "description": "Challenge UUID."
-      },
-      "Cursor": {
-        "name": "cursor",
-        "in": "query",
-        "required": false,
-        "schema": {
-          "type": "string"
-        }
-      },
-      "Size": {
-        "name": "size",
-        "in": "query",
-        "required": false,
-        "schema": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100,
-          "default": 20
-        }
-      }
-    },
-    "responses": {
-      "Unauthorized": {
-        "description": "Missing or invalid authentication.",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResponse"
-            }
-          }
-        }
-      },
-      "NotFound": {
-        "description": "Resource not found.",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResponse"
-            }
-          }
-        }
-      },
-      "BadRequest": {
-        "description": "Request validation failed.",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResponse"
-            }
-          }
-        }
-      },
-      "Conflict": {
-        "description": "Transition not allowed in current challenge state.",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ConflictError"
-            }
-          }
-        }
-      }
-    },
-    "schemas": {
-      "HealthResponse": {
-        "type": "object",
-        "required": [
-          "status",
-          "stage",
-          "service"
-        ],
-        "properties": {
-          "status": {
-            "type": "string",
-            "enum": [
-              "ok"
-            ]
-          },
-          "stage": {
-            "type": "string",
-            "example": "dev"
-          },
-          "service": {
-            "type": "string",
-            "example": "focus-pocus-api"
-          }
-        }
-      },
-      "ErrorResponse": {
-        "type": "object",
-        "required": [
-          "status",
-          "error"
-        ],
-        "properties": {
-          "status": {
-            "type": "integer",
-            "format": "int32"
-          },
-          "error": {
-            "type": "string"
-          }
-        }
-      },
-      "ConflictError": {
-        "type": "object",
-        "required": [
-          "status",
-          "error",
-          "reason"
-        ],
-        "properties": {
-          "status": {
-            "type": "integer",
-            "enum": [
-              409
-            ]
-          },
-          "error": {
-            "type": "string"
-          },
-          "reason": {
-            "type": "string",
-            "enum": [
-              "already_transitioned",
-              "too_many_active",
-              "deadline_passed"
-            ]
-          }
-        }
-      },
-      "ChallengeSuggested": {
-        "type": "object",
-        "required": [
-          "id",
-          "challenge_template_id",
-          "category",
-          "title",
-          "description",
-          "badge_image_url",
-          "default_duration_hours",
-          "status",
-          "suggested_at"
-        ],
-        "properties": {
-          "id": {
-            "type": "string",
-            "description": "Unique suggestion-instance id (UUID)."
-          },
-          "challenge_template_id": {
-            "type": "string",
-            "description": "FK to the challenge template."
-          },
-          "category": {
-            "type": "string",
-            "description": "Open string category propagated from the template."
-          },
-          "title": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string"
-          },
-          "badge_image_url": {
-            "type": "string"
-          },
-          "default_duration_hours": {
-            "type": "integer",
-            "minimum": 1,
-            "description": "How many hours the user has to complete the challenge once accepted."
-          },
-          "status": {
-            "type": "string",
-            "enum": [
-              "suggested"
-            ]
-          },
-          "suggested_at": {
-            "type": "string",
-            "format": "date-time"
-          }
-        }
-      },
-      "ChallengeActive": {
-        "type": "object",
-        "required": [
-          "id",
-          "challenge_template_id",
-          "category",
-          "title",
-          "description",
-          "badge_image_url",
-          "status",
-          "accepted_at",
-          "deadline",
-          "time_remaining_ms"
-        ],
-        "properties": {
-          "id": {
-            "type": "string",
-            "description": "Unique challenge-instance id (UUID)."
-          },
-          "challenge_template_id": {
-            "type": "string"
-          },
-          "category": {
-            "type": "string"
-          },
-          "title": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string"
-          },
-          "badge_image_url": {
-            "type": "string"
-          },
-          "status": {
-            "type": "string",
-            "enum": [
-              "active"
-            ]
-          },
-          "accepted_at": {
-            "type": "string",
-            "format": "date-time"
-          },
-          "deadline": {
-            "type": "string",
-            "format": "date-time"
-          },
-          "time_remaining_ms": {
-            "type": "integer",
-            "minimum": 0,
-            "description": "Milliseconds remaining until the deadline (clamped to >= 0)."
-          }
-        }
-      },
-      "ActiveChallengeListResponse": {
-        "type": "object",
-        "required": [
-          "results",
-          "total"
-        ],
-        "properties": {
-          "results": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/ChallengeActive"
-            }
-          },
-          "total": {
-            "type": "integer",
-            "minimum": 0
-          }
-        }
-      },
-      "AchievementFeedItem": {
-        "type": "object",
-        "required": [
-          "id",
-          "category",
-          "title",
-          "description",
-          "status",
-          "just_unlocked"
-        ],
-        "properties": {
-          "id": {
-            "type": "string"
-          },
-          "challenge_template_id": {
-            "type": "string",
-            "nullable": true,
-            "description": "Set for challenge-based items; null for v1 static catalog unlocks."
-          },
-          "category": {
-            "type": "string"
-          },
-          "title": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string"
-          },
-          "badge_image_url": {
-            "type": "string",
-            "nullable": true
-          },
-          "icon": {
-            "type": "string",
-            "nullable": true,
-            "description": "Kept for v1 catalog unlock compatibility."
-          },
-          "status": {
-            "type": "string",
-            "enum": [
-              "active",
-              "completed",
-              "expired"
-            ]
-          },
-          "accepted_at": {
-            "type": "string",
-            "format": "date-time",
-            "nullable": true
-          },
-          "deadline": {
-            "type": "string",
-            "format": "date-time",
-            "nullable": true
-          },
-          "time_remaining_ms": {
-            "type": "integer",
-            "minimum": 0,
-            "nullable": true,
-            "description": "Milliseconds remaining until the deadline; null for non-active items."
-          },
-          "unlocked_at": {
-            "type": "string",
-            "format": "date-time",
-            "nullable": true,
-            "description": "When the achievement was unlocked; null for active challenges."
-          },
-          "xp_awarded": {
-            "type": "integer",
-            "minimum": 0,
-            "nullable": true,
-            "description": "XP awarded on unlock; null for active challenges."
-          },
-          "just_unlocked": {
-            "type": "boolean",
-            "description": "True if the item was completed within the last 60 seconds."
-          }
-        }
-      },
-      "AchievementFeedListResponse": {
-        "type": "object",
-        "required": [
-          "results",
-          "total"
-        ],
-        "properties": {
-          "results": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/AchievementFeedItem"
-            }
-          },
-          "total": {
-            "type": "integer",
-            "minimum": 0
-          }
-        }
-      },
-      "EventIngestRequest": {
-        "type": "object",
-        "required": [
-          "event_id",
-          "event_type",
-          "actor_user_id",
-          "occurred_at"
-        ],
-        "properties": {
-          "event_id": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 256,
-            "description": "Idempotency key — same id is rejected (already-accepted) on retry."
-          },
-          "event_type": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 128
-          },
-          "actor_user_id": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 128
-          },
-          "occurred_at": {
-            "type": "string",
-            "format": "date-time"
-          },
-          "properties": {
-            "type": "object",
-            "additionalProperties": true
-          }
-        }
-      },
-      "EventAccepted": {
-        "type": "object",
-        "required": [
-          "accepted"
-        ],
-        "properties": {
-          "accepted": {
-            "type": "boolean",
-            "enum": [
-              true
-            ]
-          }
-        }
-      }
-    }
-  }
-}