shade-plugins-notion 0.1.0__py3-none-any.whl

shade_plugins_notion/__init__.py

@@ -0,0 +1,534 @@
+"""O plugin ``notion``: consultar uma base, criar uma página (sem duplicar) e atualizar uma página
+no Notion, sob o contrato de plugin do shade-sdk, com o token OAuth da conexão da plataforma.
+
+```toml
+[hosts]
+permitidos = ["api.notion.com"]
+
+[conexoes]
+nomes = ["notion"]
+
+[plugins]
+notion = "0.1.0"
+```
+
+```python
+import shade_plugins_notion as notion
+
+pendentes = notion.consultar_base(BASE, filtro={"property": "Status", "select": {"equals": "Novo"}})
+
+with item.efetivar("registrar o pedido"):
+    nova = notion.criar_pagina(BASE, {"Nome": notion.titulo(f"Pedido {item['numero']}")})
+    notion.atualizar_pagina(nova["id"], {"Observação": notion.texto(item["detalhe"])})
+```
+
+- **Conta:** a conexão ``notion`` da plataforma (Conectores). O robô nunca vê a senha nem o refresh
+  token: o token de acesso chega sob demanda e é renovado pela plataforma. No laptop, ponha um token
+  em ``SHADE_TOKEN_NOTION``. O Notion não tem escopos: a conexão vê o que a pessoa compartilhou com
+  ela, e o que não foi compartilhado responde ``404``.
+- **Base:** o id da base (da URL dela). O plugin lê as fontes de dados da base; com mais de uma, passe
+  ``fonte=`` (o nome ou o id); sem ele, é ``ErroDeNegocio`` (``FonteNaoEscolhida``) com os nomes.
+- **Ler não muda nada:** ``consultar_base`` roda inclusive no ensaio.
+- **Escrever só dentro de** ``item.efetivar()`` (no ensaio não roda). ``criar_pagina`` exige na base a
+  coluna de texto ``Chave Shade`` (sem ela, ``ColunaAusente`` antes de qualquer escrita), grava nela a
+  chave do item e consulta por ela antes de criar. Depois de despachado, o pedido de criação nunca é
+  repetido: sem confirmação, o plugin confere no Notion e, sem achar a página, o erro é
+  ``NotionIncerto``. ``atualizar_pagina`` é idempotente por natureza: refazer grava os mesmos valores.
+- **Propriedades** vão no formato da API do Notion, montadas como objeto e serializadas por
+  ``json.dumps``; ``titulo()`` e ``texto()`` montam as de texto, com os limites do Notion.
+- **Prazo:** ``timeout=`` (30 s) vale para a chamada inteira, retentativas incluídas.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Iterator, Mapping
+from typing import Any
+
+from shade_sdk import http
+from shade_sdk.plugins import Plugin
+
+from shade_plugins_notion import _cliente
+from shade_plugins_notion._cliente import CONEXAO, NOTION, VERSAO_DA_API, Cliente, Prazo
+from shade_plugins_notion.erros import (
+    ColunaAusente,
+    ErroDoNotion,
+    FonteNaoEscolhida,
+    NaoEncontrado,
+    NotionIncerto,
+    NotionNaoSaiu,
+)
+
+__version__ = "0.1.0"
+
+#: A coluna de texto que leva a chave do item: o que faz o refazer achar a página.
+COLUNA_DA_CHAVE = "Chave Shade"
+#: Quantas páginas a consulta devolve, no máximo, e quantas o Notion dá por pedido (o teto dele é
+#: 100, e a resposta pode trazer menos que isso mesmo sem ter acabado).
+LIMITE_MAX = 5_000
+POR_PEDIDO = 100
+PEDIDOS_MAX = 60
+PROPRIEDADES_MAX = 100
+#: Os limites do Notion para um valor de texto: partes de até 2.000 caracteres (em UTF-16), até 100.
+PARTE_MAX = 2_000
+PARTES_MAX = 100
+
+_ID = re.compile(
+    r"^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}$"
+)
+_CURSOR = re.compile(r"^[A-Za-z0-9_\-=+/.:]{1,2000}$")
+_CHAVE_DO_ITEM = re.compile(r"^[A-Za-z0-9_\-]{1,128}$")
+
+PLUGIN = Plugin(
+    "notion",
+    __version__,
+    shade_sdk=">=0.22.3,<0.23",
+    dono="Equipe de integrações da ShadeOne",
+    hosts=[NOTION],
+    conexoes=[CONEXAO],
+)
+
+__all__ = [
+    "COLUNA_DA_CHAVE",
+    "PLUGIN",
+    "VERSAO_DA_API",
+    "ColunaAusente",
+    "ErroDoNotion",
+    "FonteNaoEscolhida",
+    "NaoEncontrado",
+    "NotionIncerto",
+    "NotionNaoSaiu",
+    "atualizar_pagina",
+    "consultar_base",
+    "criar_pagina",
+    "texto",
+    "texto_de",
+    "titulo",
+]
+
+
+# ── os valores de texto ──────────────────────────────────────────────────────────────────
+
+
+def _partes(valor: Any, nome: str) -> list[dict[str, Any]]:
+    """O texto em partes de ``rich_text``: cada parte é ``text.content``, literal (um ``**`` ou um
+    link do dado vai como texto)."""
+    if not isinstance(valor, str):
+        raise ValueError(f"{nome} é um texto")
+    if "\x00" in valor:
+        raise ValueError(f"{nome} não leva o caractere nulo")
+    partes: list[str] = []
+    atual: list[str] = []
+    unidades = 0
+    for caractere in valor:
+        tamanho = 2 if ord(caractere) > 0xFFFF else 1
+        if unidades + tamanho > PARTE_MAX:
+            partes.append("".join(atual))
+            atual, unidades = [], 0
+        atual.append(caractere)
+        unidades += tamanho
+    if atual:
+        partes.append("".join(atual))
+    if len(partes) > PARTES_MAX:
+        raise ValueError(f"{nome} passa do limite do Notion ({PARTES_MAX} partes de {PARTE_MAX})")
+    return [{"type": "text", "text": {"content": parte}} for parte in partes]
+
+
+def titulo(valor: str) -> dict[str, Any]:
+    """O valor de uma propriedade de título: ``{"Nome": notion.titulo("Pedido 12")}``."""
+    return {"title": _partes(valor, "titulo")}
+
+
+def texto(valor: str) -> dict[str, Any]:
+    """O valor de uma propriedade de texto: ``{"Observação": notion.texto("conferido")}``."""
+    return {"rich_text": _partes(valor, "texto")}
+
+
+def texto_de(propriedade: Any) -> str:
+    """O texto de uma propriedade de título ou de texto lida do Notion (``""`` se não for uma)."""
+    if not isinstance(propriedade, Mapping):
+        return ""
+    partes = propriedade.get("title") or propriedade.get("rich_text") or []
+    if not isinstance(partes, list):
+        return ""
+    return "".join(str(p.get("plain_text", "")) for p in partes if isinstance(p, Mapping))
+
+
+# ── validação ────────────────────────────────────────────────────────────────────────────
+
+
+def _porta(porta: Any) -> int | None:
+    if porta is not None and (
+        not isinstance(porta, int) or isinstance(porta, bool) or not 0 < porta < 65536
+    ):
+        raise ValueError(f"porta é um número de 1 a 65535, não {porta!r}")
+    return porta
+
+
+def _limite(valor: Any) -> int:
+    if not isinstance(valor, int) or isinstance(valor, bool) or not 0 < valor <= LIMITE_MAX:
+        raise ValueError(f"limite é um número de 1 a {LIMITE_MAX}")
+    return valor
+
+
+def _id(valor: Any, nome: str) -> str:
+    if not isinstance(valor, str) or not _ID.fullmatch(valor):
+        raise ValueError(f"{nome} é o id do Notion (32 dígitos hexadecimais, da URL)")
+    return valor
+
+
+def _fonte(valor: Any) -> str | None:
+    if valor is None:
+        return None
+    if not isinstance(valor, str) or not valor.strip() or len(valor) > 200:
+        raise ValueError("fonte é o nome ou o id de uma fonte de dados da base")
+    return valor.strip()
+
+
+def _serializavel(valor: Any, nome: str) -> None:
+    try:
+        json.dumps(valor, allow_nan=False)
+    except (TypeError, ValueError):
+        raise ValueError(f"{nome} tem um valor que não vira JSON") from None
+
+
+def _filtro(valor: Any) -> dict[str, Any] | None:
+    if valor is None:
+        return None
+    if not isinstance(valor, Mapping):
+        raise ValueError("filtro é o filtro da API do Notion, um dicionário")
+    saida = dict(valor)
+    _serializavel(saida, "filtro")
+    return saida
+
+
+def _propriedades(valor: Any) -> dict[str, Any]:
+    """As propriedades do robô. A coluna da chave é do plugin: o robô que a sobrescreve faria o
+    refazer não achar a página."""
+    if not isinstance(valor, Mapping) or not 0 < len(valor) <= PROPRIEDADES_MAX:
+        raise ValueError(f"propriedades é um dicionário de 1 a {PROPRIEDADES_MAX} propriedades")
+    saida: dict[str, Any] = {}
+    for nome, conteudo in valor.items():
+        if not isinstance(nome, str) or not nome.strip():
+            raise ValueError("o nome de uma propriedade é um texto não vazio")
+        if nome.strip().casefold() == COLUNA_DA_CHAVE.casefold():
+            raise ValueError(
+                f"{COLUNA_DA_CHAVE} é preenchida pelo plugin: não passe em propriedades"
+            )
+        if not isinstance(conteudo, Mapping):
+            raise ValueError(
+                f"o valor de {nome!r} é o da API do Notion, um dicionário "
+                '(notion.titulo("x"), notion.texto("x"), {"number": 1})'
+            )
+        saida[nome] = dict(conteudo)
+    _serializavel(saida, "propriedades")
+    return saida
+
+
+def _chave_do_item(chamada: Any) -> str:
+    chave = chamada.idempotencia
+    if not isinstance(chave, str) or not _CHAVE_DO_ITEM.fullmatch(chave):
+        raise ValueError("a chave de idempotência do item não serve para a coluna da chave")
+    return chave
+
+
+# ── a base ───────────────────────────────────────────────────────────────────────────────
+
+
+def _cliente_da_chamada(chamada: Any, porta: Any) -> Cliente:
+    return Cliente(chamada=chamada, prazo=Prazo(chamada.timeout), porta=_porta(porta))
+
+
+def _lendo(operacao: str, funcao: Callable[[], Any]) -> Any:
+    """A falha de rede no meio da leitura vira ``ErroDoNotion``."""
+    try:
+        return funcao()
+    except ErroDoNotion:
+        raise
+    except OSError as exc:
+        raise _cliente.falha_de_leitura(operacao, exc) from exc
+
+
+def _fonte_da_base(
+    cliente: Cliente, operacao: str, base: str, fonte: str | None, chave: str | None = None
+) -> str:
+    """O id da fonte de dados da base (a consulta e a página nova falam com ela). Com mais de uma e
+    sem ``fonte=``, ``FonteNaoEscolhida``."""
+    resposta = cliente.pedir("GET", f"/v1/databases/{base}", idempotencia=chave)
+    dados = _cliente.checar_leitura(operacao, resposta)
+    fontes = [
+        f
+        for f in dados.get("data_sources") or []
+        if isinstance(f, dict) and isinstance(f.get("id"), str) and _ID.fullmatch(f["id"])
+    ]
+    nomes = ", ".join(sorted(str(f.get("name") or f["id"]) for f in fontes))
+    if not fontes:
+        raise FonteNaoEscolhida("Notion: a base não tem nenhuma fonte de dados que a conexão veja")
+    if fonte is None:
+        if len(fontes) > 1:
+            raise FonteNaoEscolhida(
+                f"Notion: a base tem mais de uma fonte de dados ({nomes}); passe fonte= com o nome "
+                "de uma delas"
+            )
+        return fontes[0]["id"]
+    pedido = fonte.casefold()
+    achadas = [
+        f for f in fontes if pedido in (str(f.get("name", "")).casefold(), f["id"].casefold())
+    ]
+    if len(achadas) != 1:
+        raise FonteNaoEscolhida(f"Notion: a fonte {fonte!r} não é uma das da base ({nomes})")
+    return achadas[0]["id"]
+
+
+def _exigir_a_coluna(cliente: Cliente, operacao: str, fonte_id: str, chave: str) -> None:
+    """Sem a coluna de texto da chave, a página nova não teria como ser achada no refazer: a recusa
+    vem antes de qualquer escrita."""
+    resposta = cliente.pedir("GET", f"/v1/data_sources/{fonte_id}", idempotencia=chave)
+    dados = _cliente.checar_leitura(operacao, resposta)
+    colunas = dados.get("properties")
+    coluna = colunas.get(COLUNA_DA_CHAVE) if isinstance(colunas, dict) else None
+    if not isinstance(coluna, dict):
+        raise ColunaAusente(f"A base não tem a coluna '{COLUNA_DA_CHAVE}'")
+    if coluna.get("type") != "rich_text":
+        raise ColunaAusente(
+            f"A coluna '{COLUNA_DA_CHAVE}' da base não é de texto (é {coluna.get('type')!r})"
+        )
+
+
+# ── consultar ────────────────────────────────────────────────────────────────────────────
+
+
+def _paginas_da_consulta(
+    cliente: Cliente,
+    operacao: str,
+    fonte_id: str,
+    filtro: Mapping[str, Any] | None,
+    limite: int,
+    chave: str | None = None,
+) -> Iterator[dict[str, Any]]:
+    """As páginas da consulta, seguindo o ``next_cursor``. O Notion pode devolver menos que o pedido
+    (até nenhuma) sem ter acabado: quem decide é o ``has_more``. O que não dá para ler até o fim é
+    erro, nunca um resultado cortado em silêncio: "não achei" aqui decide se a página é criada."""
+    devolvidas = 0
+    cursor = ""
+    for _ in range(PEDIDOS_MAX):
+        corpo: dict[str, Any] = {"page_size": min(POR_PEDIDO, limite - devolvidas)}
+        if filtro is not None:
+            corpo["filter"] = filtro
+        if cursor:
+            corpo["start_cursor"] = cursor
+        resposta = cliente.pedir(
+            "POST", f"/v1/data_sources/{fonte_id}/query", corpo=corpo, idempotencia=chave
+        )
+        dados = _cliente.checar_leitura(operacao, resposta)
+        for pagina in dados.get("results") or []:
+            # Numa wiki, a consulta também devolve fontes de dados: só a página interessa.
+            if isinstance(pagina, dict) and pagina.get("object") == "page":
+                yield pagina
+                devolvidas += 1
+                if devolvidas >= limite:
+                    return
+        if dados.get("has_more") is not True:
+            return
+        proximo = dados.get("next_cursor")
+        if not isinstance(proximo, str) or not _CURSOR.fullmatch(proximo) or proximo == cursor:
+            raise ErroDoNotion(f"Notion {operacao}: a resposta diz que há mais e não dá o cursor")
+        cursor = proximo
+    raise ErroDoNotion(f"Notion {operacao}: a consulta passou de {PEDIDOS_MAX} pedidos")
+
+
+def _resumo(pagina: Mapping[str, Any]) -> dict[str, Any]:
+    propriedades = pagina.get("properties")
+    return {
+        "id": str(pagina.get("id", "")),
+        "url": str(pagina.get("url", "")),
+        "propriedades": propriedades if isinstance(propriedades, dict) else {},
+    }
+
+
+@PLUGIN.operacao
+def consultar_base(
+    chamada: Any,
+    base: str,
+    filtro: Mapping[str, Any] | None = None,
+    *,
+    limite: int = 100,
+    fonte: str | None = None,
+    porta: int | None = None,
+) -> list[dict[str, Any]]:
+    """As páginas da ``base`` (o id, da URL dela) que atendem ao ``filtro`` (o da API do Notion), até
+    ``limite``, seguindo o ``next_cursor``. Cada uma: ``id``, ``url`` e ``propriedades`` (no formato
+    do Notion; ``texto_de`` lê as de texto). Nada muda no Notion. ``NaoEncontrado``: a base não existe
+    ou não foi compartilhada com a conexão. ``FonteNaoEscolhida``: a base tem mais de uma fonte de
+    dados e ``fonte=`` não foi dado."""
+    base = _id(base, "base")
+    pedido = _filtro(filtro)
+    limite = _limite(limite)
+    nome = _fonte(fonte)
+    cliente = _cliente_da_chamada(chamada, porta)
+
+    def ler() -> list[dict[str, Any]]:
+        fonte_id = _fonte_da_base(cliente, "consultar_base", base, nome)
+        paginas = _paginas_da_consulta(cliente, "consultar_base", fonte_id, pedido, limite)
+        return [_resumo(p) for p in paginas]
+
+    return _lendo("consultar_base", ler)
+
+
+# ── criar ────────────────────────────────────────────────────────────────────────────────
+
+
+def _pagina_com_a_chave(cliente: Cliente, fonte_id: str, chave: str) -> dict[str, Any] | None:
+    """A página da fonte que leva a chave. Confere o valor além de filtrar por ele: quem responde
+    sem aplicar o filtro não faz outra página passar por esta."""
+    filtro = {"property": COLUNA_DA_CHAVE, "rich_text": {"equals": chave}}
+    # Sem teto de resultados: aqui, parar antes do fim seria "não achei" sem ter lido tudo. Quem
+    # encerra a leitura sem fim é o teto de pedidos, que é erro.
+    teto = PEDIDOS_MAX * POR_PEDIDO + 1
+    paginas = _paginas_da_consulta(cliente, "criar_pagina", fonte_id, filtro, teto, chave)
+    for pagina in paginas:
+        propriedades = pagina.get("properties")
+        if isinstance(propriedades, dict) and texto_de(propriedades.get(COLUNA_DA_CHAVE)) == chave:
+            return pagina
+    return None
+
+
+def _resultado(pagina: Mapping[str, Any], *, reaproveitada: bool) -> dict[str, Any]:
+    return {
+        "id": str(pagina.get("id", "")),
+        "url": str(pagina.get("url", "")),
+        "reaproveitada": reaproveitada,
+    }
+
+
+def _conferir_depois_da_duvida(
+    cliente: Cliente, fonte_id: str, chave: str, gravado: str | None
+) -> dict[str, Any] | None:
+    """A página pode ter sido criada: o que a confirma é a chave nela. Esta leitura não prova que
+    nada saiu, então nenhuma falha dela vira "não saiu"."""
+    try:
+        achada = _pagina_com_a_chave(cliente, fonte_id, chave)
+        if achada is not None or gravado is None or not _ID.fullmatch(gravado):
+            return achada
+        # O Notion disse qual página gravou e a consulta ainda não a enxerga.
+        resposta = cliente.pedir("GET", f"/v1/pages/{gravado}", idempotencia=chave)
+        pagina = _cliente.checar_leitura("criar_pagina", resposta)
+    except (ErroDoNotion, OSError, http.NadaSaiu):
+        return None
+    propriedades = pagina.get("properties")
+    if isinstance(propriedades, dict) and texto_de(propriedades.get(COLUNA_DA_CHAVE)) == chave:
+        return pagina
+    return None
+
+
+@PLUGIN.efeito
+def criar_pagina(
+    chamada: Any,
+    base: str,
+    propriedades: Mapping[str, Any],
+    *,
+    fonte: str | None = None,
+    porta: int | None = None,
+) -> dict[str, Any]:
+    """Cria a página na ``base`` (o id), só dentro de ``item.efetivar()``. ``propriedades`` vão no
+    formato do Notion (``{"Nome": notion.titulo("x"), "Valor": {"number": 1}}``). Devolve ``id``,
+    ``url`` e ``reaproveitada`` (``True`` quando a página desta mesma chamada já existia).
+
+    Não duplica: a base precisa da coluna de texto ``Chave Shade``, o plugin a preenche com a chave
+    do item e consulta por ela antes de criar. ``ColunaAusente``: a base não tem a coluna, e nada foi
+    escrito. ``NaoEncontrado``: a base não existe ou não foi compartilhada com a conexão.
+    ``NotionNaoSaiu``: nada foi criado (o Notion recusou, a rede não abriu, a consulta não foi
+    feita). ``NotionIncerto``: o pedido saiu sem confirmação e a página não aparece na consulta; o
+    plugin não cria de novo."""
+    base = _id(base, "base")
+    pedidas = _propriedades(propriedades)
+    nome = _fonte(fonte)
+    chave = _chave_do_item(chamada)
+    cliente = _cliente_da_chamada(chamada, porta)
+    try:
+        fonte_id = _fonte_da_base(cliente, "criar_pagina", base, nome, chave)
+        _exigir_a_coluna(cliente, "criar_pagina", fonte_id, chave)
+        existente = _pagina_com_a_chave(cliente, fonte_id, chave)
+    except NaoEncontrado:
+        raise
+    except (ErroDoNotion, OSError) as exc:
+        raise NotionNaoSaiu(
+            f"Notion criar_pagina: a base não foi lida ({type(exc).__name__}); nada foi criado"
+        ) from exc
+    if existente is not None:
+        return _resultado(existente, reaproveitada=True)
+    corpo = {
+        "parent": {"type": "data_source_id", "data_source_id": fonte_id},
+        "properties": {**pedidas, COLUNA_DA_CHAVE: texto(chave)},
+    }
+    gravado: str | None = None
+    try:
+        resposta = cliente.pedir(
+            "POST", "/v1/pages", corpo=corpo, idempotencia=chave, repetir_depois_do_envio=False
+        )
+        gravado = _cliente.id_gravado(resposta)
+        _cliente.checar_escrita("criar_pagina", resposta)
+        dados = resposta.dados()
+        if not dados.get("id"):
+            raise NotionIncerto(
+                "Notion criar_pagina: a resposta não confirma a página", status=resposta.status
+            )
+        return _resultado(dados, reaproveitada=False)
+    except NotionIncerto as incerto:
+        duvida: Exception = incerto
+    except ErroDoNotion as exc:
+        duvida = NotionIncerto(f"Notion criar_pagina: a resposta não confirma a página ({exc})")
+    except OSError as exc:
+        duvida = _cliente.falha_de_escrita("criar_pagina", exc)
+        if isinstance(duvida, NotionNaoSaiu):
+            raise duvida from exc
+    achada = _conferir_depois_da_duvida(cliente, fonte_id, chave, gravado)
+    if achada is None:
+        raise duvida
+    return _resultado(achada, reaproveitada=True)
+
+
+# ── atualizar ────────────────────────────────────────────────────────────────────────────
+
+
+@PLUGIN.efeito
+def atualizar_pagina(
+    chamada: Any,
+    pagina: str,
+    propriedades: Mapping[str, Any],
+    *,
+    porta: int | None = None,
+) -> dict[str, Any]:
+    """Grava as ``propriedades`` na ``pagina`` (o id), só dentro de ``item.efetivar()``; as outras
+    ficam como estão. Devolve ``id`` e ``url``. Refazer grava os mesmos valores: é idempotente por
+    natureza, sem consulta antes. ``NotionNaoSaiu``: nada mudou (o Notion recusou, a página não existe
+    ou não foi compartilhada, a rede não abriu). ``NotionIncerto``: o pedido saiu sem confirmação;
+    refazer é seguro."""
+    pagina = _id(pagina, "pagina")
+    pedidas = _propriedades(propriedades)
+    cliente = _cliente_da_chamada(chamada, porta)
+    try:
+        # O Notion manda não repetir a escrita que deu 503 (ela pode ter gravado): quem refaz é
+        # quem conferiu.
+        resposta = cliente.pedir(
+            "PATCH",
+            f"/v1/pages/{pagina}",
+            corpo={"properties": pedidas},
+            idempotencia=chamada.idempotencia,
+            repetir_depois_do_envio=False,
+        )
+    except OSError as exc:
+        raise _cliente.falha_de_escrita("atualizar_pagina", exc) from exc
+    except ErroDoNotion as exc:
+        raise NotionIncerto(
+            f"Notion atualizar_pagina: a resposta não confirma a página ({exc})"
+        ) from exc
+    _cliente.checar_escrita("atualizar_pagina", resposta)
+    try:
+        dados = resposta.dados()
+    except ErroDoNotion as exc:
+        raise NotionIncerto(
+            f"Notion atualizar_pagina: a resposta não confirma a página ({exc})"
+        ) from exc
+    return {"id": str(dados.get("id", pagina)), "url": str(dados.get("url", ""))}

shade_plugins_notion/_cliente.py

@@ -0,0 +1,289 @@
+"""O cliente HTTP da API do Notion: o token da conexão, a versão fixa, o prazo da chamada e a
+retentativa.
+
+Fala só com ``api.notion.com`` (o host que o plugin declara), sempre com ``chamada.destino(host)``
+antes de conectar. O certificado é verificado; o ``HTTPS_PROXY`` do ambiente é respeitado (no
+sandbox, o proxy da allowlist). Não segue redirecionamento: o token não vai a outro host.
+
+O token vem de ``chamada.token(CONEXAO)``; o ``401`` (o token venceu antes da hora ou foi revogado)
+troca o token uma vez (``renovar=True``) e repete: o pedido recusado não teve efeito.
+
+A leitura repete a falha transitória, o ``429``, o ``529`` e o ``5xx`` mesmo depois do envio. A
+escrita (criar e atualizar página) só repete o que certamente não saiu: o ``429``, o ``529`` e a
+rede que recusou antes do envio. Depois do envio, a dúvida é do plugin, que confere no Notion: um
+``503`` de escrita pode ter gravado, e o próprio Notion manda não repetir.
+"""
+
+from __future__ import annotations
+
+import json
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from shade_sdk import http
+
+from shade_plugins_notion.erros import ErroDoNotion, NaoEncontrado, NotionIncerto, NotionNaoSaiu
+
+#: A conexão OAuth da plataforma de que o plugin pede o token (o provedor do catálogo).
+CONEXAO = "notion"
+NOTION = "api.notion.com"
+#: A versão fixa da API. Versão nova é minor nova do plugin, com a suíte.
+VERSAO_DA_API = "2026-03-11"
+#: Quantas vezes o pedido é tentado quando a rede ou o Notion falham de forma transitória.
+TENTATIVAS = 3
+#: A espera antes da 2ª e da 3ª tentativa (a régua do ``shade_sdk.http``).
+ESPERAS = (0.5, 1.0)
+#: O maior ``Retry-After`` que o plugin honra; acima disso, devolve o que recebeu.
+ESPERA_MAX = 10.0
+#: O teto do corpo de uma resposta lida na memória.
+RESPOSTA_MAX = 8 * 1024 * 1024
+
+
+class Prazo:
+    """O ``timeout`` da chamada como um prazo só: cada etapa usa o que sobrou."""
+
+    def __init__(self, segundos: float) -> None:
+        self.fim = time.monotonic() + segundos
+
+    def restante(self) -> float:
+        sobra = self.fim - time.monotonic()
+        if sobra <= 0:
+            raise TimeoutError("o prazo da chamada acabou")
+        return sobra
+
+    def cabe(self, espera: float) -> bool:
+        return self.fim - time.monotonic() > espera
+
+
+class _SemRedirecionamento(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+def _abridor() -> Callable[..., Any]:
+    contexto = ssl.create_default_context()
+    contexto.minimum_version = ssl.TLSVersion.TLSv1_2
+    return urllib.request.build_opener(
+        urllib.request.ProxyHandler(),
+        urllib.request.HTTPSHandler(context=contexto),
+        _SemRedirecionamento(),
+    ).open
+
+
+@dataclass
+class Resposta:
+    status: int
+    cabecalhos: Mapping[str, str]
+    corpo: bytes = b""
+
+    def cabecalho(self, nome: str) -> str:
+        for chave, valor in self.cabecalhos.items():
+            if chave.lower() == nome.lower():
+                return valor
+        return ""
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status < 300
+
+    def json(self) -> Any:
+        try:
+            return json.loads(self.corpo)
+        except ValueError as exc:
+            raise ErroDoNotion("Notion: a resposta não é JSON", status=self.status) from exc
+
+    def dados(self) -> dict[str, Any]:
+        dados = self.json()
+        if not isinstance(dados, dict):
+            raise ErroDoNotion("Notion: a resposta não é um objeto JSON", status=self.status)
+        return dados
+
+
+def transitorio(exc: BaseException) -> bool:
+    """Falha de rede em que repetir pode dar certo. O certificado inválido e o prazo esgotado,
+    não."""
+    if isinstance(exc, TimeoutError):
+        return False
+    return isinstance(exc, urllib.error.URLError | ConnectionError | ssl.SSLError) and not (
+        isinstance(exc, urllib.error.URLError)
+        and isinstance(exc.reason, ssl.SSLCertVerificationError)
+    )
+
+
+def _retry_after(resposta: Resposta) -> float:
+    """O ``Retry-After`` em segundos, limitado a ``ESPERA_MAX``."""
+    texto = resposta.cabecalho("Retry-After").strip()
+    if not texto.isdigit():
+        return 0.0
+    return min(float(texto), ESPERA_MAX)
+
+
+@dataclass
+class Cliente:
+    chamada: Any
+    prazo: Prazo
+    porta: int | None = None
+    _token: str | None = None
+    _renovou: bool = False
+
+    def url(self, caminho: str) -> str:
+        endereco = NOTION if self.porta in (None, 443) else f"{NOTION}:{self.porta}"
+        return f"https://{endereco}{caminho}"
+
+    def _bearer(self, *, renovar: bool = False) -> str:
+        if self._token is None or renovar:
+            self._token = self.chamada.token(CONEXAO, renovar=renovar)
+        return self._token
+
+    def pedir(
+        self,
+        metodo: str,
+        caminho: str,
+        *,
+        parametros: Mapping[str, str] | None = None,
+        corpo: Mapping[str, Any] | None = None,
+        idempotencia: str | None = None,
+        repetir_depois_do_envio: bool = True,
+    ) -> Resposta:
+        """Um pedido da API com o token da conexão, dentro do prazo: o ``corpo`` vai em JSON (o
+        ``json.dumps`` escapa o valor) e os ``parametros`` na consulta. Repete a falha transitória
+        de rede, o ``429``, o ``529`` e o ``5xx`` quando ``repetir_depois_do_envio`` (a leitura);
+        senão, só o que certamente não saiu (a rede que recusou antes do envio, o ``429``, o
+        ``529``). A autenticação vencida troca o token uma vez e repete. ``idempotencia`` vai no
+        ``Idempotency-Key``: o Notion não o usa, e quem observa o tráfego (o proxy, o servidor
+        falso) distingue a execução."""
+        self.chamada.destino(NOTION)
+        url = self.url(caminho)
+        if parametros:
+            url += "?" + urllib.parse.urlencode(dict(parametros))
+        dados = None if corpo is None else json.dumps(corpo, ensure_ascii=False).encode("utf-8")
+        abrir = _abridor()
+        ultima_falha: BaseException | None = None
+        ultima_resposta: Resposta | None = None
+        tentativa = 0
+        while tentativa < TENTATIVAS:
+            if tentativa:
+                espera = ESPERAS[min(tentativa - 1, len(ESPERAS) - 1)]
+                if ultima_resposta is not None:
+                    espera = max(espera, _retry_after(ultima_resposta))
+                if not self.prazo.cabe(espera):
+                    break
+                time.sleep(espera)
+            tentativa += 1
+            enviados = {
+                "Accept": "application/json",
+                "Authorization": f"Bearer {self._bearer()}",
+                "Notion-Version": VERSAO_DA_API,
+            }
+            if dados is not None:
+                enviados["Content-Type"] = "application/json; charset=utf-8"
+            if idempotencia:
+                enviados["Idempotency-Key"] = idempotencia
+            pedido = urllib.request.Request(url, data=dados, headers=enviados, method=metodo)
+            try:
+                resposta = self._despachar(abrir, pedido)
+            except Exception as exc:
+                if not transitorio(exc) or not (repetir_depois_do_envio or http.nada_saiu(exc)):
+                    raise
+                ultima_falha, ultima_resposta = exc, None
+                continue
+            if not self._renovou and resposta.status == 401:
+                # O token venceu antes da hora ou foi revogado: o pedido não teve efeito.
+                self._renovou = True
+                self._bearer(renovar=True)
+                tentativa -= 1
+                continue
+            if resposta.status in (429, 529) or (
+                resposta.status >= 500 and repetir_depois_do_envio
+            ):
+                ultima_falha, ultima_resposta = None, resposta
+                continue
+            return resposta
+        if ultima_resposta is not None:
+            return ultima_resposta
+        if ultima_falha is None:
+            raise TimeoutError("o prazo da chamada acabou")
+        raise ultima_falha
+
+    def _despachar(self, abrir: Callable[..., Any], pedido: Any) -> Resposta:
+        try:
+            with abrir(pedido, timeout=self.prazo.restante()) as resposta:
+                corpo = resposta.read(RESPOSTA_MAX + 1)
+                if len(corpo) > RESPOSTA_MAX:
+                    raise ErroDoNotion("Notion: a resposta passa do teto de leitura")
+                return Resposta(resposta.status, dict(resposta.headers.items()), corpo)
+        except urllib.error.HTTPError as exc:
+            corpo = exc.read(65536) if exc.fp else b""
+            return Resposta(exc.code, dict(exc.headers.items()), corpo)
+
+
+def checar_leitura(operacao: str, resposta: Resposta) -> dict[str, Any]:
+    """Os dados da resposta de uma leitura; o erro vira ``ErroDoNotion`` só com o status."""
+    if resposta.ok:
+        return resposta.dados()
+    if resposta.status == 404:
+        raise NaoEncontrado(
+            f"Notion {operacao}: o registro não existe, ou não foi compartilhado com a conexão (404)",
+            status=404,
+        )
+    if resposta.status in (401, 403):
+        raise ErroDoNotion(
+            f"Notion {operacao}: a conexão não tem permissão ({resposta.status}); "
+            "reconecte o Notion e compartilhe a página ou a base com ela",
+            status=resposta.status,
+        )
+    raise ErroDoNotion(
+        f"Notion {operacao}: o Notion devolveu {resposta.status}", status=resposta.status
+    )
+
+
+def checar_escrita(operacao: str, resposta: Resposta) -> Resposta:
+    """O 2xx passa; o 4xx (e o 429 e o 529 que sobraram das tentativas) é ``NotionNaoSaiu``; o erro
+    do servidor é dúvida (``NotionIncerto``)."""
+    if resposta.status >= 500 and resposta.status != 529:
+        raise NotionIncerto(
+            f"Notion {operacao}: o Notion devolveu {resposta.status}", status=resposta.status
+        )
+    if resposta.ok:
+        return resposta
+    dica = (
+        "; reconecte o Notion e compartilhe a página ou a base com ela"
+        if resposta.status in (401, 403, 404)
+        else ""
+    )
+    raise NotionNaoSaiu(
+        f"Notion {operacao}: o Notion recusou o pedido ({resposta.status}){dica}",
+        status=resposta.status,
+    )
+
+
+def id_gravado(resposta: Resposta) -> str | None:
+    """O id da página que um ``5xx`` diz ter gravado (``additional_data.committed_resource_id``:
+    o Notion salvou e não conseguiu montar a resposta)."""
+    if resposta.status < 500:
+        return None
+    try:
+        adicional = resposta.dados().get("additional_data")
+    except ErroDoNotion:
+        return None
+    gravado = adicional.get("committed_resource_id") if isinstance(adicional, dict) else None
+    return gravado if isinstance(gravado, str) else None
+
+
+def falha_de_leitura(operacao: str, exc: BaseException) -> ErroDoNotion:
+    return ErroDoNotion(f"Notion {operacao}: a conexão falhou ({type(exc).__name__})")
+
+
+def falha_de_escrita(operacao: str, exc: BaseException) -> Exception:
+    if http.nada_saiu(exc):
+        return NotionNaoSaiu(f"Notion {operacao}: a conexão não abriu ({type(exc).__name__})")
+    return NotionIncerto(
+        f"Notion {operacao}: a conexão falhou depois do envio ({type(exc).__name__}); "
+        "a alteração pode ter chegado"
+    )

shade_plugins_notion/erros.py

@@ -0,0 +1,53 @@
+"""Os erros do plugin ``notion``.
+
+Separam o que **certamente não chegou** ao Notion (``NotionNaoSaiu``, um ``http.NadaSaiu``) do que
+**pode ter chegado** (``NotionIncerto``, um ``http.ResultadoIncerto``). O token que não veio é o
+``TokenIndisponivel`` do ``shade_sdk.plugins`` (também um ``http.NadaSaiu``).
+
+As mensagens dizem a operação e o status HTTP, nunca o corpo, as propriedades nem o token.
+"""
+
+from __future__ import annotations
+
+from shade_sdk import http
+from shade_sdk.erros import ErroDeNegocio
+
+
+class ErroDoNotion(Exception):
+    """A leitura não deu certo: conexão, TLS, permissão ou o Notion recusou o pedido."""
+
+    def __init__(self, mensagem: str, *, status: int | None = None) -> None:
+        super().__init__(mensagem)
+        self.status = status
+
+
+class NaoEncontrado(ErroDoNotion):
+    """A base ou a página não existe, ou não foi compartilhada com a conexão (``404``)."""
+
+
+class ColunaAusente(ErroDeNegocio):
+    """A base não tem a coluna de texto ``Chave Shade``, sem a qual ``criar_pagina`` não sabe se a
+    página já existe. Nada foi escrito."""
+
+
+class FonteNaoEscolhida(ErroDeNegocio):
+    """A base tem mais de uma fonte de dados e a chamada não disse qual (``fonte=``), ou a fonte
+    pedida não é uma delas. A mensagem lista os nomes."""
+
+
+class NotionNaoSaiu(http.NadaSaiu):
+    """Certamente sem efeito: o Notion recusou o pedido (4xx, inclusive o 429 que sobrou das
+    retentativas), estava sobrecarregado (529) ou a rede falhou antes do envio."""
+
+    def __init__(self, mensagem: str, *, status: int | None = None) -> None:
+        super().__init__(mensagem)
+        self.status = status
+
+
+class NotionIncerto(http.ResultadoIncerto):
+    """Pode ter tido efeito: o pedido foi enviado e a resposta não veio, veio com erro do servidor
+    ou não se leu. Conferir no Notion antes de concluir que não chegou."""
+
+    def __init__(self, mensagem: str, *, status: int | None = None) -> None:
+        super().__init__(mensagem)
+        self.status = status

shade_plugins_notion-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: shade-plugins-notion
+Version: 0.1.0
+Summary: Consultar uma base, criar página (sem duplicar, pela coluna "Chave Shade") e atualizar página no Notion, com o token OAuth da conexão da plataforma.
+Author: ShadeOne
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: shade-sdk<0.23,>=0.22.3
+Description-Content-Type: text/markdown
+
+# shade-plugins-notion
+
+Consulta uma base, cria uma página (sem duplicar) e atualiza uma página no
+[Notion](https://developers.notion.com/), de dentro de um robô do
+[`shade-sdk`](https://pypi.org/project/shade-sdk/), com o token OAuth da conexão do Notion na
+plataforma. Só a biblioteca padrão do Python: nenhuma dependência além do `shade-sdk`.
+
+No `shade.toml` do robô, o host da API vai em `[hosts] permitidos` e a conexão em `[conexoes]`:
+
+```toml
+[hosts]
+permitidos = ["api.notion.com"]
+
+[conexoes]
+nomes = ["notion"]
+
+[plugins]
+notion = "0.1.0"
+```
+
+```python
+import shade_plugins_notion as notion
+
+BASE = "0f1e2d3c4b5a69788796a5b4c3d2e1f0"  # o id, da URL da base
+
+# Leitura: roda inclusive no ensaio.
+novos = notion.consultar_base(BASE, filtro={"property": "Status", "select": {"equals": "Novo"}})
+nomes = [notion.texto_de(p["propriedades"]["Nome"]) for p in novos]
+
+# Escrita: só dentro de item.efetivar() (no ensaio não roda).
+with item.efetivar("registrar o pedido"):
+    nova = notion.criar_pagina(
+        BASE,
+        {"Nome": notion.titulo(f"Pedido {item['numero']}"), "Valor": {"number": item["valor"]}},
+    )
+    notion.atualizar_pagina(nova["id"], {"Observação": notion.texto(item["detalhe"])})
+```
+
+## Antes de usar
+
+- **Crie na base a coluna de texto `Chave Shade`.** É o que faz `criar_pagina` não duplicar. Sem ela,
+  a operação recusa com `ColunaAusente` (um `ErroDeNegocio`) antes de qualquer escrita. A coluna é do
+  plugin: não a edite, e o robô não pode passá-la em `propriedades`.
+- **Compartilhe a base com a conexão.** O Notion não tem escopos: a conexão só vê o que a pessoa
+  escolheu ao conectar ou adicionou depois no menu da página. O que não foi compartilhado responde
+  `404`, igual ao que não existe.
+
+## A conta
+
+- **Conexão:** o robô nunca vê a senha nem o refresh token. O token de acesso chega sob demanda da
+  conexão `notion` da plataforma e é renovado por ela. Fora da plataforma (no laptop), ponha um token
+  em `SHADE_TOKEN_NOTION`.
+- **Fonte de dados:** uma base do Notion pode ter mais de uma. O plugin lê as da base a cada chamada;
+  com mais de uma, passe `fonte=` (o nome ou o id); sem ele, o erro é `FonteNaoEscolhida` (um
+  `ErroDeNegocio`) e a mensagem lista os nomes.
+- **Versão da API:** `Notion-Version: 2026-03-11`, fixa. Versão nova da API é versão nova do plugin.
+
+## O que o plugin garante
+
+- **Página sem duplicar.** `criar_pagina` grava a chave do item na coluna `Chave Shade` e, antes de
+  criar, consulta a base por ela; achando, devolve a página (`reaproveitada=True`). Depois de
+  despachado, o pedido de criação nunca é repetido: se a resposta se perde, o plugin consulta de novo
+  e, sem achar, o erro é `NotionIncerto` (a página pode existir: confira no Notion antes de refazer).
+- **Atualização idempotente por natureza.** `atualizar_pagina` grava os valores pedidos, e refazer
+  grava os mesmos. Ela também não se repete sozinha depois do envio: o Notion avisa que a escrita que
+  respondeu `503` pode ter gravado. Sem confirmação, é `NotionIncerto`, e refazer é seguro.
+- **Só dentro de `item.efetivar()`.** Fora dele, a operação é um erro de contrato antes de qualquer
+  byte; no ensaio, o bloco é pulado e nada é enviado.
+- **Valores literais.** As propriedades são objetos serializados por `json.dumps`, e `titulo()` e
+  `texto()` põem o dado em `text.content`: um `**` ou um link do dado vai como texto. Os ids são
+  validados antes de qualquer pedido.
+- **Host e prazo:** só `api.notion.com`, com o certificado verificado, sem seguir redirecionamento;
+  toda chamada aceita `timeout=` (30 s por padrão), que vale para a chamada inteira.
+- **Sem conteúdo em evento nem em erro:** cada chamada emite um evento com a operação, o host, a
+  duração e o status. Nunca as propriedades, o token nem o corpo da resposta.
+
+## Operações
+
+| Operação | Efeito | O que faz |
+|---|---|---|
+| `consultar_base(base, filtro=None, *, limite=100, fonte=None)` | não | Páginas da base: `id`, `url` e `propriedades`. `filtro` é o da API do Notion. Segue o `next_cursor`. |
+| `criar_pagina(base, propriedades, *, fonte=None)` | sim | Cria a página na base. Devolve `id`, `url` e `reaproveitada`. |
+| `atualizar_pagina(pagina, propriedades)` | sim | Grava as propriedades pedidas. Devolve `id` e `url`. |
+
+`propriedades` vão no formato da API do Notion, pelo nome da coluna: `{"Valor": {"number": 1}}`,
+`{"Status": {"select": {"name": "Feito"}}}`. Para as de texto, `notion.titulo("x")` e
+`notion.texto("x")` montam o valor e dividem o texto longo nas partes que o Notion aceita. Na leitura,
+`notion.texto_de(propriedade)` devolve o texto.
+
+## Limites
+
+- Se alguém mover para a lixeira ou arquivar a página antes de um refazer, a consulta não a enxerga, e
+  o refazer cria outra.
+- A consulta pode demorar a enxergar a página recém-criada. Por isso, a dúvida depois de uma resposta
+  perdida pode ficar `NotionIncerto`.
+- `consultar_base` devolve até 5.000 páginas por chamada.
+- Conteúdo da página (blocos), arquivo e criação de base ficam fora do plugin.
+
+## Testes
+
+A suíte de contrato do `shade_sdk.testing.plugins` e um servidor falso da API (TLS de uma CA de
+teste, que recusa propriedade desconhecida, de outro tipo ou acima dos limites de texto, como a de
+verdade) acompanham o código-fonte em `tests/`.

shade_plugins_notion-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+shade_plugins_notion/__init__.py,sha256=9rYmrP3MC7ErhisYJ_gznpgV8OwoS1Qia8ereg74Bts,22412
+shade_plugins_notion/_cliente.py,sha256=2915Q-rFva2G5ifuUSgWr704FDpd_vIHQ97hQF33P_E,11402
+shade_plugins_notion/erros.py,sha256=i0kZobH5crFnUU5OPwoHj0qfpcJB7_BxACiwrmJLZyM,2021
+shade_plugins_notion-0.1.0.dist-info/METADATA,sha256=9WcUAu8KUcJBGqqzWAk889sKlPiY61vdLIG38HrRlGI,5764
+shade_plugins_notion-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+shade_plugins_notion-0.1.0.dist-info/entry_points.txt,sha256=DGmLpwUsEEfDmVaMe-uJXT3GXBrG36uQxZXK9xY096g,57
+shade_plugins_notion-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+shade_plugins_notion-0.1.0.dist-info/RECORD,,

shade_plugins_notion-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

shade_plugins_notion-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[shade_sdk.plugins]
+notion = shade_plugins_notion:PLUGIN

shade_plugins_notion-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.