aivi.api

Shared auth and error vocabulary for the @source api / OpenAPI capability surface.

This module is intentionally small: it does not issue requests on its own. It provides the sum and alias types that the OpenAPI source guide and runtime use when configuring API-backed signals and tasks.

use aivi.api (
    ApiAuth
    ApiError
    ApiResponse
    BearerToken
)

---

ApiError

The current API error surface:

type ApiError =
  | ApiTimeout
  | ApiDecodeFailure Text
  | ApiRequestFailure Text
  | ApiUnauthorized
  | ApiNotFound
  | ApiServerError Text

use aivi.api (
    ApiDecodeFailure
    ApiError
    ApiNotFound
    ApiRequestFailure
    ApiServerError
    ApiTimeout
    ApiUnauthorized
)

type ApiError -> Text
func describeApiError =
 ||> ApiTimeout                -> "Timed out"
 ||> ApiDecodeFailure message  -> "Decode failed: {message}"
 ||> ApiRequestFailure message -> "Request failed: {message}"
 ||> ApiUnauthorized           -> "Unauthorized"
 ||> ApiNotFound               -> "Not found"
 ||> ApiServerError message    -> "Server error: {message}"

---

ApiAuth

Auth configuration for API-backed sources and operations:

type ApiAuth =
  | BearerToken Text
  | BasicAuth Text Text
  | ApiKey Text
  | ApiKeyQuery Text
  | OAuth2 Text

use aivi.api (
    ApiAuth
    BearerToken
)

value auth : ApiAuth = BearerToken "secret-token"

ApiKeyQuery is the query-parameter variant. BearerToken and OAuth2 both map to bearer-style authorization headers in the current runtime.

---

ApiSource

Marker type used by the OpenAPI capability layer.

use aivi.api (ApiSource)

type SourceHandle = ApiSource

---

ApiResponse A

Convenience alias for the current API result shape:

use aivi.api (ApiError)

type ApiResponse A =
  Result ApiError A

use aivi.api (ApiResponse)

type User = {
    id: Int,
    name: Text
}

value userResult : ApiResponse User =
    Ok {
        id: 1,
        name: "Ada"
    }

Remaining public constructors and aliases

ApiTimeout reports a timed-out request. ApiDecodeFailure message reports response decoding failure, ApiRequestFailure message reports transport failure, ApiUnauthorized represents an authorization failure, ApiNotFound represents a missing resource, and ApiServerError message represents a server failure.

BasicAuth username password and ApiKey key are authentication values. ApiResponse A is an alias for Result ApiError A.