# Catalog Tasks

## Domain Types

### Task

- `Task = object { id, created_at, operation, 9 more }`

  - `id: string`

  - `created_at: string`

  - `operation: TaskOperation`

    - `"create"`

    - `"delete"`

  - `status: TaskStatus`

    - `"pending"`

    - `"running"`

    - `"completed"`

    - `"failed"`

  - `updated_at: string`

  - `error_message: optional string`

  - `install_id: optional string`

  - `links: optional array of object { href, rel, properties, 2 more }`

    - `href: string`

      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: string`

      Link relation type.

    - `properties: optional map[unknown]`

      Additional metadata keyed by property name.

    - `titles: optional map[string]`

      Human-readable titles keyed by BCP 47 language tag.

    - `type: optional string`

      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 string`

  - `package_slug: optional string`

  - `package_version: optional number`

  - `warnings: optional array of object { code, details, message, 4 more }`

    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: "validation_error" or "bad_request" or "unauthorized" or 6 more`

      - `"validation_error"`

      - `"bad_request"`

      - `"unauthorized"`

      - `"forbidden"`

      - `"not_found"`

      - `"conflict"`

      - `"rate_limit_exceeded"`

      - `"internal_error"`

      - `"service_unavailable"`

    - `details: array of object { code, field, message }`

      - `code: "validation_error" or "bad_request" or "unauthorized" or 6 more`

        - `"validation_error"`

        - `"bad_request"`

        - `"unauthorized"`

        - `"forbidden"`

        - `"not_found"`

        - `"conflict"`

        - `"rate_limit_exceeded"`

        - `"internal_error"`

        - `"service_unavailable"`

      - `field: string`

        valid json path for request body

      - `message: string`

        error message for specific error

    - `message: string`

      summary of the error

    - `path: string`

    - `request_id: string`

    - `status: number`

      HTTP Status Code

    - `timestamp: string`

### Task Operation

- `TaskOperation = "create" or "delete"`

  - `"create"`

  - `"delete"`

### Task Status

- `TaskStatus = "pending" or "running" or "completed" or "failed"`

  - `"pending"`

  - `"running"`

  - `"completed"`

  - `"failed"`