flowlit-integration 0.1.0__tar.gz

flowlit_integration-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,91 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: python -m pip install -e ".[dev,all]"
+
+      - name: Test
+        run: python -m pytest -q
+
+      - name: Type check
+        run: python -m mypy src
+
+      - name: Lint
+        run: python -m ruff check src tests
+
+  release-build:
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      url: https://pypi.org/p/flowlit-integration
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

flowlit_integration-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Credentials -- this library never ships a real one, but its own tests
+# and any local smoke-testing might create one; never let it get committed.
+credentials.json
+*.credentials.json
+service-account*.json
+.env
+.env.*
+!.env.example
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

flowlit_integration-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to `flowlit-integration` are documented here. Format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
+project uses [SemVer](https://semver.org/), though pre-1.0 minor bumps
+(`0.x.0`) may include breaking changes, called out explicitly below.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-13
+
+Initial public release. Extracted from `ccq-automation`, where these
+executors originated as project-specific code, into a standalone,
+reusable library — the middle tier of `flowlit` -> `flowlit-integration`
+-> `<client application>`.
+
+### Added
+
+- Five `flowlit` executors, one per file, each independently installable
+  via its own extra:
+  - `harvest` — Harvest API v2 reads (`users`, `time_entries`, or any
+    other collection endpoint), with automatic `links.next` pagination.
+  - `google-sheets` — Google Sheets read/write/append via `gspread`.
+  - `gmail` — outbound email with attachments, via SMTP + an app
+    password.
+  - `slack` — outbound Slack messages (channel or DM) via
+    `chat.postMessage`.
+  - `spreadsheet` — generic "any rows + columns in, one `.xlsx` out"
+    executor, with multi-key row sorting (`sort_by`/`sort_direction`);
+    no dependency on any of the other four.
+- `credentials.provider`: a shared `CredentialsProvider` abstraction
+  (`Env`/`File`/`Chained`, `default_credentials_provider()`) and one
+  typed resolver per integration (`resolve_harvest_credentials`,
+  `resolve_google_sheets_credentials`, `resolve_gmail_credentials`,
+  `resolve_slack_credentials`) — explicit value > environment variable >
+  `FLOWLIT_INTEGRATION_CREDENTIALS_FILE` > a documented, not-yet-
+  implemented secret-manager extension point.
+- Registration stays the client's own explicit job — this package never
+  calls `flowlit.register_executor(...)` itself, and importing it never
+  performs I/O or touches credentials.
+- PEP 561 `py.typed` marker.
+
+[Unreleased]: https://github.com/shadiwazir/flowlit-integration/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/shadiwazir/flowlit-integration/releases/tag/v0.1.0

flowlit_integration-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shadiwazir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flowlit_integration-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: flowlit-integration
+Version: 0.1.0
+Summary: Reusable flowlit executors (Harvest, Google Sheets, Gmail, Slack, spreadsheets) and their shared credentials abstraction, for any flowlit-based client.
+Project-URL: Homepage, https://github.com/shadiwazir/flowlit-integration
+Project-URL: Repository, https://github.com/shadiwazir/flowlit-integration
+Project-URL: Issues, https://github.com/shadiwazir/flowlit-integration/issues
+Author: shadiwazir
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: flowlit>=0.4.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: aiohttp>=3.9; extra == 'all'
+Requires-Dist: google-auth>=2.0; extra == 'all'
+Requires-Dist: gspread>=6.0; extra == 'all'
+Requires-Dist: openpyxl>=3.1; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-openpyxl; extra == 'dev'
+Provides-Extra: gmail
+Provides-Extra: google-sheets
+Requires-Dist: google-auth>=2.0; extra == 'google-sheets'
+Requires-Dist: gspread>=6.0; extra == 'google-sheets'
+Provides-Extra: harvest
+Requires-Dist: aiohttp>=3.9; extra == 'harvest'
+Provides-Extra: slack
+Requires-Dist: aiohttp>=3.9; extra == 'slack'
+Provides-Extra: spreadsheet
+Requires-Dist: openpyxl>=3.1; extra == 'spreadsheet'
+Description-Content-Type: text/markdown
+
+# flowlit-integration
+
+Reusable [flowlit](https://github.com/shadiwazir/flowlit) executors for a
+handful of common external systems -- Harvest, Google Sheets, Gmail,
+Slack -- plus a generic "any data → spreadsheet" executor, and the
+shared `CredentialsProvider` abstraction they all resolve secrets
+through.
+
+## Where this sits
+
+```
+flowlit                 the execution engine: DAG plans, the Executor
+                         port, the EventBus. Knows nothing about any
+                         specific external system.
+
+flowlit-integration      (this package) knows how to talk to a handful
+                         of common external systems. Knows nothing about
+                         any particular business's use of them.
+
+<client application>    e.g. ccq-automation -- business-specific DAGs,
+                         business rules, transport. Imports the
+                         executors it needs from here and registers them
+                         with flowlit itself.
+```
+
+## Installing
+
+Pick only the extras you need -- each pulls in just the third-party SDK(s)
+that one executor requires:
+
+```
+pip install "flowlit-integration[harvest]"
+pip install "flowlit-integration[harvest,gmail,spreadsheet]"
+pip install "flowlit-integration[all]"       # everything
+```
+
+## Using an executor
+
+Registration is always the client's own explicit job -- importing this
+package never registers anything with flowlit, and never performs I/O:
+
+```python
+from flowlit import register_executor
+from flowlit_integration.executors.harvest_executor import HarvestExecutor
+
+register_executor("harvest", HarvestExecutor())
+```
+
+Each executor resolves its own credentials lazily, the first time a step
+of that type actually runs, via `flowlit_integration.credentials`'s
+`default_credentials_provider()` chain (explicit value > environment
+variable > credentials file > a documented, not-yet-implemented secret-
+manager extension point) -- see `docs/architecture.md` and each
+executor's own module docstring for its specific env-var/spec-field
+names.
+
+## Status
+
+Alpha (pre-1.0: minor version bumps may include breaking changes).
+Published on PyPI. See [CHANGELOG.md](CHANGELOG.md) for what changed in
+each release.

flowlit_integration-0.1.0/README.md

@@ -0,0 +1,61 @@
+# flowlit-integration
+
+Reusable [flowlit](https://github.com/shadiwazir/flowlit) executors for a
+handful of common external systems -- Harvest, Google Sheets, Gmail,
+Slack -- plus a generic "any data → spreadsheet" executor, and the
+shared `CredentialsProvider` abstraction they all resolve secrets
+through.
+
+## Where this sits
+
+```
+flowlit                 the execution engine: DAG plans, the Executor
+                         port, the EventBus. Knows nothing about any
+                         specific external system.
+
+flowlit-integration      (this package) knows how to talk to a handful
+                         of common external systems. Knows nothing about
+                         any particular business's use of them.
+
+<client application>    e.g. ccq-automation -- business-specific DAGs,
+                         business rules, transport. Imports the
+                         executors it needs from here and registers them
+                         with flowlit itself.
+```
+
+## Installing
+
+Pick only the extras you need -- each pulls in just the third-party SDK(s)
+that one executor requires:
+
+```
+pip install "flowlit-integration[harvest]"
+pip install "flowlit-integration[harvest,gmail,spreadsheet]"
+pip install "flowlit-integration[all]"       # everything
+```
+
+## Using an executor
+
+Registration is always the client's own explicit job -- importing this
+package never registers anything with flowlit, and never performs I/O:
+
+```python
+from flowlit import register_executor
+from flowlit_integration.executors.harvest_executor import HarvestExecutor
+
+register_executor("harvest", HarvestExecutor())
+```
+
+Each executor resolves its own credentials lazily, the first time a step
+of that type actually runs, via `flowlit_integration.credentials`'s
+`default_credentials_provider()` chain (explicit value > environment
+variable > credentials file > a documented, not-yet-implemented secret-
+manager extension point) -- see `docs/architecture.md` and each
+executor's own module docstring for its specific env-var/spec-field
+names.
+
+## Status
+
+Alpha (pre-1.0: minor version bumps may include breaking changes).
+Published on PyPI. See [CHANGELOG.md](CHANGELOG.md) for what changed in
+each release.

flowlit_integration-0.1.0/docs/architecture.md

@@ -0,0 +1,78 @@
+# Architecture
+
+## Package layout
+
+```
+src/flowlit_integration/
+  executors/            one flowlit Executor per file, one per external
+                         system (or generic capability):
+    harvest_executor.py       Harvest API v2 (users, time entries)
+    google_sheets_executor.py Google Sheets (read/write/append)
+    gmail_executor.py         outbound email via SMTP
+    slack_executor.py         outbound Slack messages
+    spreadsheet_executor.py   generic rows+columns -> .xlsx
+  credentials/           the CredentialsProvider abstraction shared by
+                         every executor above, plus one typed resolver
+                         per integration (resolve_harvest_credentials,
+                         resolve_google_sheets_credentials,
+                         resolve_gmail_credentials,
+                         resolve_slack_credentials).
+```
+
+Not included: a Slack *signing-secret* resolver (inbound webhook
+verification). None of the executors above need it -- see
+`credentials/provider.py`'s own note on why that stays a client concern.
+
+Each executor lives in exactly one file and has zero knowledge of any
+other executor. None of them import anything from a client application --
+this package's own test suite proves that by never importing
+`ccq_automation` (or any other client) anywhere.
+
+## Credentials
+
+`credentials.provider.CredentialsProvider` is a small ABC with `get`/
+`require` (the latter raising `MissingCredentialError`). Three
+implementations chain together via `default_credentials_provider()`:
+
+1. An explicit value passed directly to a resolver call (highest
+   precedence -- lets a caller override everything for a single call,
+   e.g. in a test).
+2. `EnvCredentialsProvider` -- plain environment variables.
+3. `FileCredentialsProvider` -- a flat JSON credentials file (path from
+   `CCQ_CREDENTIALS_FILE`... see the module docstring for how a client
+   points this elsewhere via its own env var naming).
+4. A documented, not-yet-implemented extension point for a cloud secret
+   manager.
+
+Each executor's constructor accepts an optional `CredentialsProvider`
+and defaults to `default_credentials_provider()` -- so constructing an
+executor, and even registering it with flowlit, never touches
+credentials or performs I/O. Resolution happens lazily, inside each
+executor's own `_run()`, the first time a step of that type is actually
+dispatched.
+
+## Registration is the client's job
+
+This package never calls `flowlit.register_executor(...)` itself, and
+never imports `flowlit.plugins`. A client wires an executor into its own
+flowlit DAGs explicitly:
+
+```python
+from flowlit import register_executor
+from flowlit_integration.executors.gmail_executor import GmailExecutor
+
+register_executor("gmail", GmailExecutor())
+```
+
+This mirrors flowlit's own plugin philosophy (explicit call, not
+automatic discovery) and keeps this package a pure library with no
+import-time side effects -- a client can import individual executor
+modules (e.g. for type-checking a spec) without registering anything.
+
+## What does *not* live here
+
+Anything specific to one business's use of these executors -- validation
+rules, data-transformation/formatting rules, DAG wiring, settings that
+aren't secrets (e.g. which Google Sheet id/tab to read) -- stays in the
+client application. This package only ever grows genuinely reusable
+"talk to external system X" code and the credential plumbing it needs.

flowlit_integration-0.1.0/docs/credentials.md

@@ -0,0 +1,107 @@
+# Credentials
+
+Every executor in this package needs at least one secret (an API token,
+a service-account key, an SMTP password) to make its outbound call. They
+all resolve it through one shared abstraction —
+[`flowlit_integration.credentials.provider`](../src/flowlit_integration/credentials/provider.py)
+— rather than each executor reading `os.environ` (or a config file) on
+its own. See that module's own docstring for the full design rationale;
+this document is the user-facing reference: what sources are supported,
+in what order, and exactly which keys each executor needs.
+
+## Why more than one source
+
+Different environments call for different ways to hand over a secret:
+
+- A **local dev shell** usually just exports environment variables.
+- A **container** (Docker Compose, a Kubernetes Pod, an Azure App
+  Service "Configuration" file mount) more often gets secrets as a
+  mounted file — one JSON document, not a pile of separate env vars.
+- A **cloud deployment** eventually wants a managed secret store, not
+  files or plain env vars at all.
+
+Rather than hardcode one of these, `CredentialsProvider` is a small,
+pluggable abstraction with a defined precedence, so a client adding a
+new source later is a one-place change (see
+[Extension point](#extension-point-a-cloud-secret-manager) below) — no
+executor code changes.
+
+## Supported sources, and precedence
+
+For any single credential lookup (say, `HARVEST_TOKEN`), sources are
+tried in this order — first hit wins:
+
+1. **Explicit / inline value.** Not a `CredentialsProvider` source at
+   all — a resolver function (e.g. `resolve_harvest_credentials`) or a
+   step's own `spec` can hand in an already-resolved value directly,
+   which is used as-is, before any provider is even consulted. This is
+   how Google Sheets' `credentials_json`/`credentials_path` spec fields
+   work.
+2. **Environment variable.** `EnvCredentialsProvider` — plain
+   `os.environ` lookup by key.
+3. **Credentials file.** `FileCredentialsProvider` — a flat JSON file:
+
+   ```json
+   {
+     "HARVEST_TOKEN": "example-harvest-token",
+     "HARVEST_ACCOUNT_ID": "1234567",
+     "SLACK_BOT_TOKEN": "xoxb-example-0000000000-0000000000000-abcdefghijklmnopqrstuvwx",
+     "GMAIL_SMTP_USERNAME": "reports@example.com",
+     "GMAIL_SMTP_APP_PASSWORD": "example-app-password",
+     "GOOGLE_APPLICATION_CREDENTIALS": "/run/secrets/google-service-account.json"
+   }
+   ```
+
+   (Placeholder values only — never commit a real one; see
+   [Keeping secrets out of git](#keeping-secrets-out-of-git).) Enabled by
+   pointing the `FLOWLIT_INTEGRATION_CREDENTIALS_FILE` environment
+   variable at this file's path. A missing file is *not* an error — it
+   just means this source contributes nothing, and resolution falls
+   through to the next source (or fails with `MissingCredentialError` if
+   nothing else has the key either). A file that exists but isn't valid
+   JSON, or isn't a flat object of strings, *is* treated as a real
+   misconfiguration and raises.
+4. **(Not yet implemented) a cloud secret manager** — see
+   [Extension point](#extension-point-a-cloud-secret-manager).
+
+The same key names are used both as environment variable names and as
+credentials-file JSON keys — moving a given secret from one source to
+the other never means renaming it.
+
+`default_credentials_provider()` is the one factory that builds this
+chain (today: env, then the credentials file if
+`FLOWLIT_INTEGRATION_CREDENTIALS_FILE` is set and points at a real file)
+— every executor's constructor defaults to it, but also accepts an
+explicit `CredentialsProvider` for tests or a non-default setup.
+
+## Keys each executor needs
+
+| Executor | Keys | Notes |
+|---|---|---|
+| `harvest` | `HARVEST_TOKEN`, `HARVEST_ACCOUNT_ID` | Personal access token + the account it scopes to. Sent as `Authorization: Bearer <token>` and `Harvest-Account-ID`. |
+| `slack` | `SLACK_BOT_TOKEN` | Bot token with the `chat:write` scope. Sent as `Authorization: Bearer <token>`. |
+| `gmail` | `GMAIL_SMTP_USERNAME`, `GMAIL_SMTP_APP_PASSWORD` | The sending Gmail address, and a Google Account *app password* (Google Account → Security → 2-Step Verification → App passwords) — not the account's normal login password. |
+| `google_sheets` | `GOOGLE_CREDENTIALS_JSON` (inline service-account JSON) **or** `GOOGLE_APPLICATION_CREDENTIALS` (path to the service-account JSON file) | Structurally different from the others — a service-account credential is a multi-field JSON document, not a single flat secret. Only one of the two is needed; both env var names are also accepted as step `spec` fields (`credentials_json` / `credentials_path`), which take precedence over the environment — see `resolve_google_sheets_credentials`. If neither is set, `gspread`'s own default local discovery (`gspread.service_account()`) is used as a last resort. |
+| `spreadsheet` | *(none)* | Purely generic — writes whatever rows it's given to an `.xlsx` file. No external system, no credentials. |
+
+## Extension point: a cloud secret manager
+
+A `KeyVaultCredentialsProvider` (Azure) or equivalent for another cloud,
+implementing `CredentialsProvider.get()`, is the natural next source for
+a client deploying there — added to the list `default_credentials_provider()`
+builds, typically after the credentials file, so an explicit local
+override still wins over the vault. Not implemented here; this paragraph
+is the documented placeholder. When a client needs it, no executor
+changes — only `default_credentials_provider()` and a new provider
+class, in this package or in the client's own code (a client can always
+pass its own `CredentialsProvider` into any executor's constructor
+instead of relying on this package's default chain at all).
+
+## Keeping secrets out of git
+
+`.gitignore` already excludes `.env`, `.env.*` (except `.env.example`),
+and common credentials-file names (`credentials.json`,
+`*.credentials.json`, `service-account*.json`) — see the repo root
+`.gitignore`. If you name your `FLOWLIT_INTEGRATION_CREDENTIALS_FILE`
+something outside those patterns, add it to `.gitignore` yourself before
+creating it.

flowlit_integration-0.1.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flowlit-integration"
+version = "0.1.0"
+description = "Reusable flowlit executors (Harvest, Google Sheets, Gmail, Slack, spreadsheets) and their shared credentials abstraction, for any flowlit-based client."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "shadiwazir" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    # The step-execution contract every executor here implements
+    # (Executor/BaseExecutor/ExecutorResult) and the spec-validation
+    # model every executor's Spec is built on. Bumped to 0.4.0 to track
+    # the current release; none of this package's own code depends on
+    # anything new in it (0.4.0 only moved workflow-status JSON
+    # formatting into flowlit itself, a concern this package never had).
+    "flowlit>=0.4.0",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/shadiwazir/flowlit-integration"
+Repository = "https://github.com/shadiwazir/flowlit-integration"
+Issues = "https://github.com/shadiwazir/flowlit-integration/issues"
+
+[project.optional-dependencies]
+# One extra per executor, so a client only pulls the third-party SDK(s)
+# that specific integration needs -- see src/flowlit_integration/executors/
+# for which executor uses which.
+harvest = [
+    "aiohttp>=3.9",
+]
+google-sheets = [
+    "gspread>=6.0",
+    "google-auth>=2.0",
+]
+gmail = [
+    # Gmail dispatch uses stdlib smtplib (via asyncio.to_thread) --
+    # no extra SDK dependency needed. Kept as a named extra anyway so
+    # `flowlit-integration[gmail]` reads consistently with its siblings
+    # even though today it resolves to nothing extra.
+]
+slack = [
+    "aiohttp>=3.9",
+]
+spreadsheet = [
+    "openpyxl>=3.1",
+]
+all = [
+    "flowlit-integration[harvest,google-sheets,gmail,slack,spreadsheet]",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-mock>=3.14",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "types-openpyxl",  # openpyxl ships no py.typed marker of its own
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flowlit_integration"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.11"
+disallow_untyped_defs = true
+warn_unused_ignores = true
+no_implicit_optional = true
+
+[[tool.mypy.overrides]]
+module = "flowlit_integration.credentials.*"
+strict = true

flowlit_integration-0.1.0/src/flowlit_integration/__init__.py

@@ -0,0 +1,26 @@
+"""flowlit-integration: reusable flowlit executors for common external
+systems (Harvest, Google Sheets, Gmail, Slack) and generic data output
+(spreadsheets), plus the shared `CredentialsProvider` abstraction they
+resolve their secrets through.
+
+This package sits in the middle of a three-tier hierarchy:
+
+    flowlit  ->  flowlit-integration  ->  <client application>
+
+`flowlit` is the execution engine (DAG plans, the `Executor` port, the
+`EventBus`) and has no knowledge of any specific external system.
+`flowlit-integration` knows how to talk to a handful of common ones, but
+nothing about any particular business's use of them. A client
+application (e.g. `ccq-automation`) imports the executors it needs from
+here, registers them with `flowlit` itself
+(`flowlit.register_executor(step_type, executor_instance)`), and wires
+them into its own business-specific DAGs.
+
+Registration is deliberately *not* automatic: importing this package, or
+any module in it, performs no registration and no I/O. A client calls
+`flowlit.register_executor(...)` explicitly for each executor it wants,
+the same way it would for an executor it wrote itself -- see each
+executor's own module docstring for its step-type name and spec shape.
+"""
+
+from __future__ import annotations