An API loaded for agents: the operations offered from its description, where it's reached, and where each credential comes from.

{:ok, analytics} =
  WardrikRest.API.load(discovery,
    name: "ga4",
    base_url: "https://analyticsdata.googleapis.com/",
    auth: %{"oauth2" => {:credential, "google"}},
    only: ["properties_runReport", "properties_getMetadata"],
    read_only: ["properties_run*"]
  )

Load it once, as your app starts or adds the API, and give it to agents as {WardrikRest, apis: [analytics]}.

Where secrets come from

A source is one of:

• {:credential, name} - the token of whoever the turn acts for, from the agent's WardrikCore.Credentials. Until they sign in, the call waits for them.
• {:key, name} - a key from the agent's WardrikCore.Keys, such as the org's own.
• A string, for a header only, sent as it is.

Secrets go only to :base_url, never into arguments, answers or errors.

Options

• :name (String.t/0) - Required. The prefix of the tools' names, as "ga4" for ga4__properties_runReport.

• :base_url (String.t/0) - Required. Where the API is reached, as "https://analyticsdata.googleapis.com/". Never read from the description.

• :auth (map of String.t/0 keys and term/0 values) - The source of each scheme the description names, as %{"oauth2" => {:credential, "google"}}. The default value is %{}.

• :schemes (map of String.t/0 keys and term/0 values) - Schemes the description doesn't name, each sent on every operation before its own, as %{"token" => :bearer}, {:header, name} or {:query, name}. :auth gives each a source. The default value is %{}.

• :headers (map of String.t/0 keys and term/0 values) - Headers every call sends that the description doesn't name, each a source, as %{"developer-token" => {:key, "ADS_TOKEN"}}. The default value is %{}.

• :argument_headers (map of String.t/0 keys and String.t/0 values) - Headers each tool takes as optional arguments, by name with what they're for, as %{"login-customer-id" => "The manager account's ID"}. The default value is %{}.

• :only (list of String.t/0) - The operations to offer, by name or glob, as ["properties_run*"]. Every operation it can sign in to unless set. The default value is ["*"].

• :read_only (list of String.t/0) - Operations that change nothing beyond GETs, by name or glob. Many APIs read with POST. The default value is [].

• :idempotent (list of String.t/0) - Operations safe to repeat beyond GET, PUT and DELETE, by name or glob. The default value is [].

• :trusted (boolean/0) - true stops labelling answers "outside". The default value is false.

• :timeout (pos_integer/0) - How long a call may take, in milliseconds. The default value is 30000.

• :max_result_bytes (pos_integer/0) - Bytes of an answer the model gets, as JSON. A longer one is cut, with a note to ask for less. The default value is 131072.

• :max_schema_bytes (pos_integer/0) - Bytes of each tool's schema, as JSON, where it can be. Types deeper than fit are named instead, and the <name>__describe tool gives their fields. The default value is 16384.

• :egress (function of arity 1) - Checks :base_url, returning :ok or {:error, reason}. Only https unless set; Wardrik's is Wardrik.Egress.public/1. The default value is &WardrikRest.API.https/1.

• :req_options (keyword/0) - Merged into every request. The default value is [].