{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://rangka-os.github.io/rangka-os/schema/0.5/connector.json",
  "title": "Rangka connector",
  "description": "Layer 3: an integration (rangka-connectors/<name>/connector.rk): how to authenticate, the events it triggers and the actions flows can call.",
  "type": "object",
  "required": [
    "name",
    "label",
    "version"
  ],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string"
    },
    "name": {
      "$ref": "model.json#/$defs/name"
    },
    "label": {
      "$ref": "model.json#/$defs/label"
    },
    "summary": {
      "$ref": "model.json#/$defs/label",
      "description": "One sentence in plain words for the catalogue (contract 0036)"
    },
    "category": {
      "$ref": "model.json#/$defs/catalogue_category"
    },
    "icon": {
      "$ref": "model.json#/$defs/icon"
    },
    "version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    },
    "vendor": {
      "type": "string"
    },
    "docs": {
      "type": "string"
    },
    "auth": {
      "type": "object",
      "required": [
        "type"
      ],
      "additionalProperties": false,
      "properties": {
        "type": {
          "enum": [
            "token",
            "oauth2",
            "basic",
            "hmac",
            "none"
          ]
        },
        "token_url": {
          "type": "string",
          "pattern": "^https://",
          "description": "oauth2: where the kernel refreshes the access token with refresh_token, client_id and client_secret (contract 0017 §8)"
        },
        "fields": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/setting"
          }
        },
        "sign": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "header",
            "key",
            "lines"
          ],
          "description": "Sign every request with an HMAC over canonical lines (DOKU Non-SNAP; contract 0002, refinement of 11 Nov 2026). Placeholders: {auth.x}, {settings.x}, {request.id} (UUID v4), {request.timestamp} (UTC), {request.method}, {request.target} (path), {request.digest} (base64 SHA-256 of the body; its line is left out without a body)",
          "properties": {
            "alg": {
              "enum": [
                "hmac-sha256",
                "sha256",
                "hmac-sha1",
                "sha1",
                "hmac-sha512",
                "sha512"
              ]
            },
            "key": {
              "type": "string",
              "description": "auth field holding the HMAC key"
            },
            "encoding": {
              "enum": [
                "hex",
                "base64"
              ]
            },
            "header": {
              "type": "string",
              "description": "header that carries the signature"
            },
            "prefix": {
              "type": "string",
              "description": "text before the signature, e.g. HMACSHA256="
            },
            "lines": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string"
              },
              "description": "joined with \\n, no trailing newline"
            },
            "headers": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              },
              "description": "headers sent with the request, each a line template (Request-Id: '{request.id}')"
            }
          }
        }
      }
    },
    "triggers": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "via"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "$ref": "model.json#/$defs/name"
          },
          "label": {
            "$ref": "model.json#/$defs/label"
          },
          "via": {
            "enum": [
              "webhook",
              "poll"
            ]
          },
          "every": {
            "type": "string",
            "pattern": "^[0-9]+(s|m|h)$",
            "description": "poll: how often, 5m by default and 1m at least (contract 0002 §A.1)"
          },
          "action": {
            "$ref": "model.json#/$defs/name",
            "description": "poll: the action of this connector sent on each poll; its answer is read like a webhook body"
          },
          "input": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "poll: the action's input, each value CEL over cursor (the stored cursor, null on the first poll) and settings"
          },
          "each": {
            "type": "object",
            "required": [
              "action",
              "items",
              "as",
              "key"
            ],
            "additionalProperties": false,
            "description": "poll: send the action once per item (an outlet): the list action is called first on every poll, and each item has its own cursor",
            "properties": {
              "action": {
                "$ref": "model.json#/$defs/name",
                "description": "the action that lists the items, called without input"
              },
              "items": {
                "type": "string",
                "description": "CEL over the list action's answer: the list of items"
              },
              "as": {
                "$ref": "model.json#/$defs/name",
                "description": "the name an item has in input and emit (outlet)"
              },
              "key": {
                "type": "string",
                "description": "CEL over the item: its stable id, which keys its cursor"
              }
            }
          },
          "cursor": {
            "type": "string",
            "description": "poll: CEL over the answer giving the next cursor (for example next_page_token); empty keeps the cursor"
          },
          "next": {
            "type": "string",
            "description": "poll: CEL over the answer giving the next page (a next_url or /path on the action's host, or a page value bound as page for input:); null or empty stops. At most 50 pages per poll; a cut poll keeps its cursor"
          },
          "verify": {
            "type": "object"
          },
          "for_each": {
            "type": "string"
          },
          "emit": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      }
    },
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "request"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "$ref": "model.json#/$defs/name"
          },
          "label": {
            "$ref": "model.json#/$defs/label"
          },
          "request": {
            "type": "object",
            "required": [
              "method",
              "url"
            ],
            "additionalProperties": false,
            "properties": {
              "method": {
                "enum": [
                  "GET",
                  "POST",
                  "PUT",
                  "PATCH",
                  "DELETE"
                ]
              },
              "url": {
                "type": "string"
              },
              "headers": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "body": {},
              "query": {
                "type": "object"
              }
            }
          },
          "input": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/setting"
            }
          },
          "output": {
            "type": "object"
          },
          "retry": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "max": {
                "type": "integer",
                "minimum": 0,
                "maximum": 25
              },
              "backoff": {
                "enum": [
                  "fixed",
                  "exponential"
                ]
              },
              "on": {
                "type": "array",
                "items": {
                  "type": "integer"
                }
              }
            }
          },
          "idempotency": {
            "type": "string"
          },
          "allow_secret_in": {
            "type": "array",
            "items": {
              "enum": [
                "query"
              ]
            },
            "uniqueItems": true,
            "description": "Lets this action send a secret in the query string for an API that takes its key there; the validator reports a warning so it stays visible in review (contract 0017 §5)"
          }
        }
      }
    },
    "settings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/setting"
      }
    },
    "hosts": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9.-]+$"
      },
      "uniqueItems": true,
      "description": "Hosts the connector talks to, e.g. [graph.facebook.com]. An action that carries a secret may only send it to these hosts (contract 0017 §5)."
    },
    "limits": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "rate": {
          "type": "string"
        },
        "note": {
          "$ref": "model.json#/$defs/label"
        }
      }
    }
  },
  "$defs": {
    "setting": {
      "type": "object",
      "required": [
        "name"
      ],
      "additionalProperties": false,
      "properties": {
        "name": {
          "$ref": "model.json#/$defs/name"
        },
        "label": {
          "$ref": "model.json#/$defs/label"
        },
        "help": {
          "$ref": "model.json#/$defs/label"
        },
        "type": {
          "type": "string"
        },
        "required": {
          "type": "boolean"
        },
        "secret": {
          "type": "boolean",
          "description": "Stored with the secrets driver; never returned by the API"
        },
        "generate": {
          "type": "boolean"
        },
        "default": {
          "$ref": "model.json#/$defs/cel"
        }
      }
    }
  }
}
