Reference Operations / External Content Sync

CTX Brevo Repo Update

Instructions for refreshing the local and GitLab-hosted Brevo documentation context repository. Brevo as an email delivery provider for transactional email, SMTP relay, and related email-sending infrastructure.

Text size
Status: publishedCreated: 06/28/2026Last updated: 06/28/2026

Document Scope

Just Headlines uses Brevo as an email delivery provider for transactional email, SMTP relay, and related email-sending infrastructure.

This document defines the repeatable process for updating the Just Headlines Brevo documentation context repository. The purpose of this task is to keep a focused copy of selected official Brevo documentation and source material available inside the Just Headlines development environment so human developers, Codex sessions, AI agents, and future MCP/RAG tooling can read the relevant Brevo API, SMTP, Node, and Python reference material locally without repeatedly relying on external website lookups or pasted documentation links.

This document is written for both human operators and AI agents. It explains what the local context repository is, why it exists, which official Brevo sources are copied into the context repository, and what PowerShell block should be run whenever the Brevo documentation context needs to be refreshed.

1. Purpose

The Brevo documentation context repository exists so that Just Headlines has a local and GitLab-hosted copy of selected official Brevo reference material needed for email, SMTP, transactional email, API, Node, and Python integration work.

Unlike the Better Auth context repository, the Brevo context repository is assembled from more than one official source. A normal git pull inside C:\dev\ctx-brevo only updates the local copy from the Just Headlines GitLab context repository. It does not refresh the context repository from Brevo's official sources.

The Brevo update process must do three things:

  1. Download the current Brevo OpenAPI YAML file.
  2. Pull the latest selected files from the official Brevo Node SDK repository.
  3. Pull the latest selected files from the official Brevo Python SDK repository.

The main Brevo developer documentation URL is:

https://developers.brevo.com/docs/getting-started

2. Operational Use

Run this task whenever the Brevo documentation context should be refreshed from official Brevo sources.

This may be done manually during active email, SMTP, transactional email, or notification development, especially before asking Codex or another AI coding agent to rely on Brevo implementation details.

After this task runs successfully, the local folder at C:\dev\ctx-brevo should contain the latest selected Brevo reference content, and the GitLab repository should contain a committed copy of that same refreshed context.

3. Source and Destination

Official Brevo developer documentation URL:

https://developers.brevo.com/docs/getting-started

OpenAPI source:

https://api.brevo.com/v3/swagger_definition_v3.yml

Official Brevo Node SDK source:

https://github.com/getbrevo/brevo-node.git

Official Brevo Python SDK source:

https://github.com/getbrevo/brevo-python.git

Local Just Headlines context repository:

C:\dev\ctx-brevo

Temporary Node source checkout:

C:\dev\_brevo-node-source

Temporary Python source checkout:

C:\dev\_brevo-python-source

GitLab context repository remote:

git@gitlab-sudostac:sudostac/ctx-brevo.git

4. What This Script Does

This script performs the following task sequence:

  1. Changes the working directory to C:\dev.
  2. Removes temporary Brevo source checkout folders if they already exist.
  3. Creates the expected local context repository folders.
  4. Downloads the current Brevo OpenAPI YAML file.
  5. Clones the official Brevo Node SDK repository.
  6. Copies selected Node SDK reference files and folders into the context repository.
  7. Captures the Node upstream commit hash used for the refresh.
  8. Clones the official Brevo Python SDK repository.
  9. Copies selected Python SDK reference files and folders into the context repository.
  10. Captures the Python upstream commit hash used for the refresh.
  11. Ensures the local context folder is a Git repository.
  12. Ensures the GitLab SSH remote is set correctly.
  13. Stages the refreshed Brevo context content.
  14. Creates a verbose Git commit only if the context content changed.
  15. Pushes the update to GitLab.
  16. Deletes the temporary Brevo source checkout folders.
  17. Shows the final Git status.

5. PowerShell Refresh Script

Run this block from a normal PowerShell window.

cd C:\dev

$ErrorActionPreference = "Stop"

$LocalRepo = "C:\dev\ctx-brevo"
$NodeSource = "C:\dev\_brevo-node-source"
$PythonSource = "C:\dev\_brevo-python-source"

$BrevoOpenApiUrl = "https://api.brevo.com/v3/swagger_definition_v3.yml"
$BrevoNodeRepo = "https://github.com/getbrevo/brevo-node.git"
$BrevoPythonRepo = "https://github.com/getbrevo/brevo-python.git"
$GitLabRemote = "git@gitlab-sudostac:sudostac/ctx-brevo.git"

function Copy-IfExists {
    param (
        [string]$Source,
        [string]$Destination
    )

    if (Test-Path $Source) {
        Copy-Item -Recurse -Force $Source $Destination
    }
}

Remove-Item -Recurse -Force $NodeSource -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force $PythonSource -ErrorAction SilentlyContinue

New-Item -ItemType Directory -Force "$LocalRepo\openapi" | Out-Null
New-Item -ItemType Directory -Force "$LocalRepo\node" | Out-Null
New-Item -ItemType Directory -Force "$LocalRepo\python" | Out-Null

Invoke-WebRequest -Uri $BrevoOpenApiUrl -OutFile "$LocalRepo\openapi\swagger_definition_v3.yml"

Remove-Item -Recurse -Force "$LocalRepo\node" -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force "$LocalRepo\node" | Out-Null

git clone --depth 1 $BrevoNodeRepo $NodeSource
cd $NodeSource
$NodeCommit = git rev-parse --short HEAD

Copy-IfExists "$NodeSource\README.md" "$LocalRepo\node\README.md"
Copy-IfExists "$NodeSource\package.json" "$LocalRepo\node\package.json"
Copy-IfExists "$NodeSource\api.ts" "$LocalRepo\node\api.ts"
Copy-IfExists "$NodeSource\src" "$LocalRepo\node\src"
Copy-IfExists "$NodeSource\docs" "$LocalRepo\node\docs"
Copy-IfExists "$NodeSource\api" "$LocalRepo\node\api"
Copy-IfExists "$NodeSource\apis" "$LocalRepo\node\apis"
Copy-IfExists "$NodeSource\model" "$LocalRepo\node\model"
Copy-IfExists "$NodeSource\models" "$LocalRepo\node\models"
Copy-IfExists "$NodeSource\lib" "$LocalRepo\node\lib"

cd C:\dev

Remove-Item -Recurse -Force "$LocalRepo\python" -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force "$LocalRepo\python" | Out-Null

git clone --depth 1 $BrevoPythonRepo $PythonSource
cd $PythonSource
$PythonCommit = git rev-parse --short HEAD

Copy-IfExists "$PythonSource\README.md" "$LocalRepo\python\README.md"
Copy-IfExists "$PythonSource\docs" "$LocalRepo\python\docs"
Copy-IfExists "$PythonSource\brevo_python" "$LocalRepo\python\brevo_python"
Copy-IfExists "$PythonSource\src" "$LocalRepo\python\src"
Copy-IfExists "$PythonSource\requirements.txt" "$LocalRepo\python\requirements.txt"
Copy-IfExists "$PythonSource\setup.py" "$LocalRepo\python\setup.py"
Copy-IfExists "$PythonSource\pyproject.toml" "$LocalRepo\python\pyproject.toml"

cd $LocalRepo

if (-not (Test-Path ".git")) {
    git init
    git branch -M main
}

git remote get-url origin *> $null
if ($LASTEXITCODE -ne 0) {
    git remote add origin $GitLabRemote
} else {
    git remote set-url origin $GitLabRemote
    git remote set-url --push origin $GitLabRemote
}

git add -A
git diff --cached --quiet

if ($LASTEXITCODE -eq 0) {
    Write-Host "No Brevo documentation context changes to commit."
} else {
    $CommitBody = @"
Refreshes the local GitLab context copy of selected official Brevo documentation and SDK reference material.

Changed behavior:
- Replaces the stored Brevo OpenAPI definition with the latest downloaded copy.
- Replaces selected Brevo Node SDK reference files with the latest upstream copy.
- Replaces selected Brevo Python SDK reference files with the latest upstream copy.
- Keeps the context repository focused on Brevo API, SMTP, Node, Python, and integration-reference material.

Source:
- Developer docs URL: https://developers.brevo.com/docs/getting-started
- OpenAPI source: https://api.brevo.com/v3/swagger_definition_v3.yml
- Node SDK source: https://github.com/getbrevo/brevo-node.git
- Python SDK source: https://github.com/getbrevo/brevo-python.git
- Node upstream commit: $NodeCommit
- Python upstream commit: $PythonCommit

Operational context:
- Maintains an updated local and GitLab-hosted documentation context for Brevo.
- Supports local review, Codex access, future documentation indexing, and future MCP/RAG workflows.
- Avoids depending on a single upstream Git pull because Brevo context material is assembled from multiple official sources.

Validation performed:
- Downloaded the current Brevo OpenAPI definition.
- Pulled selected files and folders from the official Brevo Node SDK repository.
- Pulled selected files and folders from the official Brevo Python SDK repository.
- Staged only the resulting context-repository changes.
"@

    git commit -m "Update Brevo documentation context" -m "$CommitBody"
    git push origin main
}

cd C:\dev
Remove-Item -Recurse -Force $NodeSource -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force $PythonSource -ErrorAction SilentlyContinue

cd $LocalRepo
git status

6. Expected Result

If the official Brevo context material changed, the script should create and push a new commit with this subject:

Update Brevo documentation context

If the official Brevo context material did not change, the script should print:

No Brevo documentation context changes to commit.

In either case, the final git status should show the current state of the local context repository.

7. AI Agent Instructions

When using this repository for email, SMTP, transactional email, notification, or Brevo API development, AI agents should treat C:\dev\ctx-brevo as the local Brevo documentation and source-material context.

AI agents should use the local context repository as the first reference source for Brevo-related development work. The Brevo developer website may still be used when the local context appears incomplete, stale, or insufficient for a specific implementation question.

Do not assume that a normal git pull inside C:\dev\ctx-brevo refreshes the repository from Brevo's official sources. It only refreshes the local copy from the Just Headlines GitLab context repository. To update from official Brevo sources, run the PowerShell refresh script in this document.

8. Human Operator Notes

This script is safe to run repeatedly. It replaces the stored Brevo context content with a fresh copy of the selected official source material.

The script does not store SSH keys, passphrases, tokens, Brevo API keys, Brevo SMTP credentials, Just Headlines secrets, or application configuration secrets. Git authentication is handled by the existing local SSH configuration on the operator's computer.

If GitLab blocks a push because the branch is protected, check the GitLab branch protection settings for the ctx-brevo repository and confirm that normal pushes to main are permitted for the account performing this task.

9. Validation Checklist

After running the script, confirm the following:

  1. C:\dev\ctx-brevo\openapi\swagger_definition_v3.yml exists.
  2. C:\dev\ctx-brevo\node exists.
  3. C:\dev\ctx-brevo\python exists.
  4. The local context repository contains selected Brevo OpenAPI, Node SDK, and Python SDK reference material.
  5. git status does not show unexpected staged changes.
  6. If changes were found, a commit was created.
  7. If a commit was created, it was pushed to git@gitlab-sudostac:sudostac/ctx-brevo.git.
  8. The temporary folders C:\dev\_brevo-node-source and C:\dev\_brevo-python-source were removed.

10. Related Repositories

This document concerns the Brevo documentation context repository only:

C:\dev\ctx-brevo

It does not define the Just Headlines email, SMTP, transactional email, or notification implementation itself. The implementation belongs in the applicable Just Headlines application repository.