# Catalog Tasks

## Domain Types

### Task

- `class Task: …`

  - `id: str`

  - `created_at: datetime`

  - `operation: TaskOperation`

    - `"create"`

    - `"delete"`

  - `status: TaskStatus`

    - `"pending"`

    - `"running"`

    - `"completed"`

    - `"failed"`

  - `updated_at: datetime`

  - `error_message: Optional[str]`

  - `install_id: Optional[str]`

  - `links: Optional[List[Link]]`

    - `href: str`

      Target reference.

      Fragment URIs (`#name`) reference other entities in the same graph by
      their local name (the key in the entity map). Absolute paths and URLs reference
      external resources outside the graph.

    - `rel: str`

      Link relation type.

    - `properties: Optional[Dict[str, object]]`

      Additional metadata keyed by property name.

    - `titles: Optional[Dict[str, str]]`

      Human-readable titles keyed by BCP 47 language tag.

    - `type: Optional[str]`

      Media type of the target resource (per RFC 7033 section 4.4.4.3).
      Applies to external `href`s; typically omitted for intra-graph references.

  - `package_id: Optional[str]`

  - `package_slug: Optional[str]`

  - `package_version: Optional[int]`

  - `warnings: Optional[List[Warning]]`

    Informational warnings about the task outcome. For delete tasks,
    warns when adopted entities (pre-existing resources not created by
    the catalog) will be preserved rather than deleted.

    - `code: Literal["validation_error", "bad_request", "unauthorized", 6 more]`

      - `"validation_error"`

      - `"bad_request"`

      - `"unauthorized"`

      - `"forbidden"`

      - `"not_found"`

      - `"conflict"`

      - `"rate_limit_exceeded"`

      - `"internal_error"`

      - `"service_unavailable"`

    - `details: List[WarningDetail]`

      - `code: Literal["validation_error", "bad_request", "unauthorized", 6 more]`

        - `"validation_error"`

        - `"bad_request"`

        - `"unauthorized"`

        - `"forbidden"`

        - `"not_found"`

        - `"conflict"`

        - `"rate_limit_exceeded"`

        - `"internal_error"`

        - `"service_unavailable"`

      - `field: str`

        valid json path for request body

      - `message: str`

        error message for specific error

    - `message: str`

      summary of the error

    - `path: str`

    - `request_id: str`

    - `status: int`

      HTTP Status Code

    - `timestamp: datetime`

### Task Operation

- `Literal["create", "delete"]`

  - `"create"`

  - `"delete"`

### Task Status

- `Literal["pending", "running", "completed", "failed"]`

  - `"pending"`

  - `"running"`

  - `"completed"`

  - `"failed"`