Cinesolve Instagram Automator

Cinesolve Instagram Automator turns CineSolve reviews in Notion into scheduled Instagram posts. It ingests eligible Notion pages, normalizes review data, renders post images, builds captions, schedules posts through Postiz, and keeps local status in sync.

The workflow is intentionally manual at the Notion boundary: a review is only processed when its Notion Publication status is set to To be published.

What It Does

• Ingests review pages from Notion and stores normalized review data locally.
• Renders Instagram-ready review images.
• Generates captions with review details, ratings, dynamic tags, and Instagram character-limit protection.
• Recalculates freshness scores so the scheduler can prioritize timely reviews.
• Schedules, updates, cancels, and verifies posts through the Postiz API.
• Retries failed Postiz posts after publication checks.
• Treats Notion as the source of truth for manual published overrides.
• Supports Telegram notifications and manual workflow commands.
• Exposes a small API with optional API-key protection and rate limiting.

Requirements

• Python 3.10+
• A Notion internal integration token
• A Notion database shared with that integration
• A Postiz API key and base URL
• uv recommended, though editable pip installs also work

Setup

1. Create API Credentials

Create a Notion integration using the official Notion developer flow, then share the review database with that integration and copy the database ID.

Create or copy your Postiz API key from Postiz settings.

2. Install Dependencies

Using uv:

uv sync

Using a virtual environment and pip:

python3 -m venv venv
source venv/bin/activate
pip install -e .

3. Configure Environment

Copy the example environment file:

cp .env.example .env

Set the required values:

NOTION_API_TOKEN=...
NOTION_DATABASE_ID=...
POSTIZ_API_KEY=...
POSTIZ_BASE_URL=...

Optional Telegram notifications and commands:

TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...

API security is enabled by default for /api/* routes:

CSI_API_KEY=...
CSI_API_REQUIRE_AUTH=true
CSI_API_RATE_LIMIT_ENABLED=true
CSI_API_RATE_LIMIT_MAX_REQUESTS=...
CSI_API_RATE_LIMIT_WINDOW_SECONDS=...
CSI_API_RATE_LIMIT_MAX_SUBJECTS=...

For local development only, API-key enforcement can be disabled:

CSI_API_REQUIRE_AUTH=false

File downloads are restricted to HTTPS and trusted hosts. Adjust these only when the Notion file host list changes:

FILE_DOWNLOAD_ALLOWED_HOSTS=...
FILE_DOWNLOAD_BLOCK_PRIVATE_NETWORKS=true

Daily Usage

Run the full workflow:

cinesolve run-all

run-all performs these steps in order:

1. Applies Notion published overrides.
2. Checks Postiz publication status for due posts.
3. Ingests Notion reviews marked To be published.
4. Recalculates freshness scores.
5. Renders missing or stale images.
6. Rebuilds the Postiz schedule.

Individual Commands

Ingest eligible Notion reviews:

cinesolve ingest eligible

Recalculate all freshness scores:

cinesolve ingest recalculate-freshness

Render review images:

cinesolve render

Schedule through Postiz:

cinesolve postiz schedule

Check Postiz status for posts at least 30 minutes past their scheduled time:

cinesolve postiz check-status

Inspect the Notion schema:

cinesolve ingest inspect-schema

Dump processed Notion pages as JSON Lines:

cinesolve ingest dump

Start the Telegram listener manually:

cinesolve notify listen-telegram

Scheduler Mode

When RUN_SCHEDULER=true, the app runs as a daemon-style scheduler:

• Starts the Telegram listener when Telegram is enabled.
• Starts the Postiz status checker.
• Schedules the daily run-all from CRON_SCHEDULE.

It does not run run-all immediately on startup. Trigger a manual run with cinesolve run-all or Telegram /run_all.

Telegram Commands

When the listener is running, the configured chat can use:

• /run_all or /run-all to run the full workflow.
• /queue to show queued reviews.
• /scheduled to show scheduled reviews.
• /failed to show failed reviews.
• /next_check to show the next Postiz status check time.
• /help to show available commands.

Operational Workflows

Add a New Review

1. Create the review in Notion.
2. Fill the required review fields.
3. Set Publication status to To be published.
4. Run cinesolve run-all.

Update an Existing Review

1. Edit the review in Notion.
2. Set Publication status back to To be published.
3. Run cinesolve run-all.

If the review is already scheduled, the scheduler updates the Postiz post when needed.

Prioritize a Review

Check the Notion Priority checkbox before running the workflow. Priority reviews are placed ahead of non-priority reviews within the scheduler rules.

After Postiz confirms a priority post as PUBLISHED, the app clears the Notion checkbox so the boost is not reused accidentally.

Remove a Scheduled Post Manually

If a review is scheduled in Postiz but should no longer publish, set its Notion Publication status to Published. On the next cinesolve run-all, the app cancels the scheduled Postiz post and marks the review as posted locally.

Adjust Freshness Scoring

1. Change FRESH_WINDOW_DAYS in .env.
2. Run cinesolve ingest recalculate-freshness.
3. Run cinesolve postiz schedule.

Utility Scripts

Utility scripts live in @assistant_scripts/.

Inspect Postiz posts for a date range:

python @assistant_scripts/check_postiz_posts.py

Delete all non-published Postiz posts:

python @assistant_scripts/delete_non_published_postiz_posts.py

That delete script is destructive. It removes draft, scheduled, failed, and other non-published posts from Postiz after confirmation prompts.

Development

Install dependencies:

uv sync

Run tests:

uv run pytest

Run linting:

uv run ruff check .

The Notion SDK is wrapped by csi_ingest.notion_api_client.NotionClient so SDK and Notion API version changes stay isolated from the rest of the application.