Connector files

A connector file declares one connector. Write it in Python (.py) or Starlark (.star). Both describe the same thing.

The connector

class Acme(BaseConnector):
    id = "custom_acme"
    name = "Acme Tickets"
    summary = "Look up and open tickets in Acme."
    category = Category.PRODUCTIVITY
    fields = (address(label="Acme address", placeholder="https://tickets.acme.example.com"),)
    auth = (ApiKey(credential("API key", min_length=16)),)
    check = Check("/api/me")

Attribute
`id`	Must start with `custom_`.
`name`, `summary`	What people see in the console.
`category`	Where it shows up in the app library.
`fields`	What the admin fills in at install. Usually `address(...)`: where your app lives.
`auth`	How it signs in. See below.
`check`	A request that proves the login works, for example `Check("/api/me")`.
`modes`	Whether the app signs in once for the workspace, per person, or both.
`errors`	Plain hints per status code, which agents read: `Errors(hints={404: "Nothing there."})`.
`headers`	Fixed headers on every request. You cannot set `Authorization`, `Host` and similar headers.
`docs`	An `https` link to your app’s API docs.
`icon`	A plain word.

Tools are functions in the class, decorated with @tool.script. See Scripts.

Signing in

Login	Python	Starlark
API key or token	`ApiKey(credential("API key", min_length=16))`	`api_key("API key")`
Username and password	`UserPassword(credential("Password", min_length=8))`	`user_password("Password")`

Python files can also declare sign-in steps for apps that log in with a form or a JSON call (sign_in_steps = form_login(...)), and extra secrets a script needs besides the login, such as a signing key (Secret) or a TOTP seed (Totp). The admin enters them at install, and scripts never see their values.

OAuth sign-in in a custom connector must use your own OAuth client (client=OwnClient()).

A login must be at least 8 characters long.

Imports

A .py file may only import names from:

console_api.connectors.core and its modules: the connector building blocks.
console_api.connectors.core.script: the names a script uses (request, ok, fail, attempt, html, xml, json, re, …).
console_api.connectors.lib.<module>: shared helpers such as dig.
typing, collections.abc, __future__, functools.partial, datetime.timedelta.

Use these imports exactly as in the examples.

Rules

A file is refused, with the line and the reason, when it has:

an import outside the list above, import x, import *, or a relative import;
code at the top level other than imports, constants, functions and the class;
exec, eval, open, __import__ and similar built-ins, or any name starting with two underscores;
non-ASCII names, or invisible or bidirectional characters;
loops, comprehensions and lambdas outside a script;
a decorator other than @tool.<kind>(...), or more than one connector in a file;
an id that does not start with custom_;
an address that is not a public https address. Your real, private address is typed in at install, not written in the file.

A connector can have up to 100 tools.