@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1Solutions.Input.t()
) ::
  {:ok, ArchAstro.Types.SolutionImportResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Import a Solution into the library

Imports a Solution and its bundled configs (skills, scripts, templates, files) into the library for the target scope. Two mutually exclusive import modes are supported: pass solution to re-import an existing system-owned catalog Solution by ID or lookup_key, or pass solution_bundle to supply a self-contained inline bundle. Exactly one must be present.

The operation upserts the bundle in a single transaction. When dry_run is true the same pipeline runs but the transaction is rolled back — no rows are persisted and the response reflects what would have been written. The response shape is the same in both cases: the Solution summary plus installed_configs listing each config the import created or would create.

Pairs with POST /api/v1/solutions/:solution/install: this endpoint puts the Solution into the library; install provisions a runtime resource (Agent, AgentRoutine, AgentTool, etc.) from an already-imported Solution.

The imported Solution in summary form, plus installed_configs — one entry per config the transaction created or would create in dry_run mode. installed_configs is deprecated; prefer the solution summary shape for new integrations.

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Delete a Solution

Permanently deletes an imported Solution and all configs bundled with it, including templates, skills, scripts, and files. The deletion runs in a single transaction; provider-stored blobs are swept asynchronously after commit.

Org-scope callers (for example, an org admin in the Library settings page) can only delete their org's copy of the Solution. App-scope callers can delete Solutions at either scope. RBAC is enforced inside the core delete flow.

Returns 204 No Content on success.

Empty body. HTTP 204 indicates the Solution was deleted successfully.

@spec dependents(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.SolutionDependentsResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Preview Solution delete impact

Returns a read-only preview of what deleting the specified Solution would affect: the agents that reference the Solution's bundle, and the count of bundled configs that would be orphaned rather than cascade-deleted.

Use this endpoint before calling DELETE /api/v1/solutions/:solution to surface a warning when live agents depend on the Solution.

Visibility scope mirrors the delete endpoint: org-scope viewers see their org's copy; app-scope viewers can inspect either scope.

Agents that reference this Solution's bundle plus the count of configs that would be orphaned on delete.

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.SolutionSummary.t()}
  | {:error, ArchAstro.Error.reason()}

Retrieve a Solution

Returns a single Solution identified by its config ID (cfg_...) or lookup_key, in the same summary shape the list endpoint emits. The response always includes a freshly-minted readme_url — call this endpoint to refresh an expired README token without making any other state change.

Visibility matches the list endpoint: app-level Solutions (no org affiliation) are visible to everyone — including unauthenticated callers, so the public catalog can render a Solution's detail page logged-out; org-scoped Solutions are only visible to authenticated viewers whose org context matches. Anything else returns 404.

When the resolved Solution is org-scoped, the endpoint compares its solution_version against the matching app-level copy. If the app-level copy is at a higher version the response includes upgrade_available: true and latest_version. App-level resolutions always report upgrade_available: false.

Solution summary including a freshly-minted readme_url token valid for one hour.

@spec image(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1SolutionsSolutionImage.Params.t()
) :: {:ok, Req.Response.t()} | {:error, ArchAstro.Error.reason()}

Fetch a Solution cover image or gallery screenshot

Returns the raw bytes of a Solution's cover image — the bundled asset the Solution body's image: field names — or, with the optional file param, one of its gallery screenshots (screenshots: entries). This endpoint backs the image_url and screenshot_urls fields of catalog payloads (such as GET /api/v1/solutions), which anonymous consumers — the public marketplace's page cache, OpenGraph scrapers — may hold far longer than a signed storage URL lives. Authorization is performed via a short, stable capability token rather than an HTTP header, so the URL never expires.

The token is an HMAC-based capability tied to the Solution config ID. It does not expire, but the endpoint checks at fetch time that the Solution still declares the requested image — without file, that it still declares a cover; with file, that the path is still among the body's declared image/screenshots — so republishing without the asset (or hiding the Solution) turns the URL into a 404. Shared caches may continue serving the old image until the Cache-Control max-age of one hour elapses. v is an opaque cache key minted alongside the token; it changes when the Solution changes and is ignored by verification.

All failure modes — invalid config ID, invalid token, hidden Solution, no declared cover, a file outside the declared set, or an asset that doesn't resolve to a bundled image — return a uniform 404 to avoid acting as an existence oracle.

Raw cover image bytes, served with the asset's image content type.

@spec install(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1SolutionsSolutionInstall.Input.t()
) ::
  {:ok, ArchAstro.Types.SolutionInstallResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Install a Solution

Provisions a runtime resource from an already-imported Solution. The type of resource created depends on the template the Solution wraps: an AgentTemplate produces an Agent, an AutomationTemplate produces an Automation, and attachment templates (AgentRoutineTemplate, AgentToolTemplate, AgentSkillTemplate, AgentComputerTemplate) attach a sub-resource to an existing Agent specified by target.

For Solutions that bundle more than one template, pass template (the ID or lookup_key of the desired template) to select which one to provision. Single-template Solutions do not require template.

Pairs with POST /api/v1/solutions (import): import puts the Solution into the library; install provisions a runtime resource from it.

The provisioned runtime resource (Agent, Automation, AgentRoutine, AgentTool, AgentSkill, or AgentComputer) together with the source Solution's config ID.

@spec list(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.GetApiV1Solutions.Params.t()
) ::
  {:ok, ArchAstro.Types.SolutionListResponse.t()}
  | {:error, ArchAstro.Error.reason()}

List Solutions

Returns a paginated list of Solutions visible to the caller, merging two scopes: app-level Solutions (system-owned rows with no org affiliation, visible to everyone — including unauthenticated callers — so they can power the public catalog) and org-level Solutions (system-owned rows stamped with the viewer's org ID, included when an authenticated viewer carries an org context). Unauthenticated callers resolve to an app-scoped anonymous viewer and therefore only ever see the app-level scope.

Solutions that appear under both scopes are deduplicated by their stable solution_id value. The merged entry's owners array lists every scope the Solution was found under ("system" and/or "org"). When the app-level copy has a higher solution_version than the org-level copy, the response includes upgrade_available: true and latest_version so callers can prompt for an upgrade.

Paginated list of Solution summaries visible to the caller.

@spec readme(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1SolutionsSolutionReadme.Params.t()
) :: {:ok, Req.Response.t()} | {:error, ArchAstro.Error.reason()}

Retrieve a Solution README or asset

Serves the README markdown or a bundled asset for an imported Solution. Both modes use the same path and require a short-lived signed token in the query string rather than an Authorization header, so browsers can load asset URLs directly from <img src> attributes without custom request logic.

When file is omitted the response is the Solution's readme field rendered as text/markdown. All local asset references in the markdown are rewritten to point back at this endpoint with ?file=PATH&token=TOKEN so browsers can load images inline without additional authentication.

When file is set the response is the raw bytes of the matching asset (a File child whose relative_path equals PATH, or an inline assets entry by name) with the asset's stored Content-Type.

Tokens are scoped to a single Solution, carry the viewer's app, org, and sandbox context from the time they were minted, and expire after one hour. Obtain a fresh token by calling GET /api/v1/solutions/:solution, which always returns a newly minted readme_url.

README markdown (text/markdown) when file is omitted, or the raw asset bytes with the asset's Content-Type when file is set.

@spec upgrade(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1SolutionsSolutionUpgrade.Input.t()
) ::
  {:ok, ArchAstro.Types.SolutionUpgradeResponse.t()}
  | {:error, ArchAstro.Error.reason()}

Upgrade an installed Solution

Applies an incoming bundle to an already-installed Solution in a single atomic transaction, bringing its configs in line with the new bundle. Config IDs are preserved across the upgrade. Configs that existed in the old bundle but are absent from the new one are orphaned (top-level) or hard-deleted (child rows).

Two mutually exclusive source modes: pass target_solution to pull the incoming bundle from an existing Solution by ID or lookup_key, or pass solution_bundle to supply a complete inline bundle directly. Exactly one must be present.

When dry_run is true the full diff is computed and returned but no changes are written. Pass the dry-run response's review_fingerprint as expected_review_fingerprint when applying to guard against the bundle changing between review and apply.

Updated Solution plus the full upgrade diff.

@spec view(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1SolutionsSolutionView.Input.t()
) :: {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Track a Solution detail-page view

Records a solution_viewed analytics event for the identified Solution and returns 204 No Content. Fired by the marketplace when a Solution's detail page is rendered in a browser, so publishers can see impressions alongside installs in their Solution analytics.

Visibility matches GET /api/v1/solutions/:solution: unauthenticated callers (the logged-out marketplace) can only track Solutions published to the public catalog; anything the caller could not retrieve returns 404 and records nothing.

Pass anonymous (the analytics visitor ID) so logged-out views can be counted as unique viewers. The event's Solution and publisher attribution are resolved server-side from the Solution row — never from request input.

Empty body. HTTP 204 indicates the Solution view was recorded successfully.