cortexdb-connectors 0.2.1__tar.gz → 0.2.5__tar.gz

{cortexdb_connectors-0.2.1 → cortexdb_connectors-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-connectors
-Version: 0.2.1
+Version: 0.2.5
 Summary: Data connectors for CortexDB — ingest from Slack, GitHub, GitLab, Jira, Linear, Confluence, Notion, PagerDuty, Discord, Teams, Google Workspace, Salesforce, HubSpot, Zendesk, Intercom, and ServiceNow into the v1 memory API.
 Author-email: CortexDB Team <team@cortexdb.ai>
 License-Expression: Apache-2.0
@@ -82,6 +82,15 @@ Managed data connectors for [CortexDB](https://cortexdb.ai). Run them yourself,
 
 Each connector pulls from a third-party system (Slack, GitHub, Jira, …) and writes every event into CortexDB as a v1 experience.
 
+## Plan availability (audit BLK-3)
+
+| Mode | Plan | What it means |
+|---|---|---|
+| **Self-hosted** (`cortexdb-sync` CLI) | 🟢 **Free** (this package) | You run the poller / webhook receiver yourself. Cursor state lives in `~/.cortexdb/`. Every connector below works in this mode. |
+| **Managed sync** (dashboard) | 🔒 **Starter+** ($29/mo) | CortexDB hosts the syncer, manages credentials, and surfaces health in the dashboard. The "Add Connector" button in the dashboard is gated on this plan. |
+
+The free self-hosted path is always available; the managed dashboard path is what the pricing page calls "Starter+". The badge below appears on each connector's setup page for the same reason.
+
 ## Install
 
 ```bash
@@ -115,7 +124,7 @@ export CORTEXDB_ACTOR=user:u_019e...
 export CORTEXDB_SCOPE_TEMPLATE='org:acme/source:{source}'   # optional
 ```
 
-`{source}` (and `{tenant}`, `{namespace}`, `{actor}`, `{entity.<type>}`) get filled in per event.
+`{source}` (and `{scope}`, `{namespace}`, `{actor}`, `{entity.<type>}`) get filled in per event. (`{tenant}` is still accepted as a legacy alias of `{scope}`.)
 
 ## Run
 
@@ -141,6 +150,8 @@ cortexdb-sync status
 
 ## Available connectors
 
+All 16 connectors are **🟢 Free** to self-host and **🔒 Starter+** ($29/mo) to use via the managed dashboard.
+
 ```
 slack            SLACK_BOT_TOKEN
 github           GITHUB_TOKEN
@@ -160,7 +171,9 @@ intercom         INTERCOM_TOKEN
 servicenow       SNOW_INSTANCE, SNOW_USERNAME, SNOW_PASSWORD
 ```
 
-Per-connector setup pages live at https://cortexdb.ai/docs/connectors/ (e.g. [Slack](https://cortexdb.ai/docs/connectors/slack)).
+Per-connector setup pages live at https://cortexdb.ai/docs/connectors/ (e.g. [Slack](https://cortexdb.ai/docs/connectors/slack)). **The "Add Connector" button on those pages is the managed (Starter+) path** — the CLI on this page is the free path.
+
+For deep self-hosted operation — auth lifetimes, cursor state, retries, OAuth setup for Salesforce/Teams/Google Workspace — see [`SELF_HOSTING.md`](./SELF_HOSTING.md) in this directory.
 
 ## YAML config
 
@@ -188,11 +201,15 @@ from cortexdb_connectors.slack import SlackConnector
 connector = SlackConnector(
     cortex_url="https://api-v1.cortexdb.ai",
     cortex_api_key="v4.public...",
-    actor="user:u_019e...",
-    scope_template="org:acme/source:slack/channel:{entity.channel}",
+    scope="org:acme/source:slack",
     slack_bot_token="xoxb-...",
     channels=["C01ABC", "C02DEF"],
 )
+# actor + a richer scope_template are set after construction:
+connector.bind(
+    actor="user:u_019e...",
+    scope_template="org:acme/source:slack/channel:{entity.channel}",
+)
 
 result = asyncio.run(connector.sync())
 print(result.episodes_ingested, "ingested,", len(result.errors), "errors")

{cortexdb_connectors-0.2.1 → cortexdb_connectors-0.2.5}/README.md

@@ -1,129 +1,146 @@
-# cortexdb-connectors
-
-Managed data connectors for [CortexDB](https://cortexdb.ai). Run them yourself, or let CortexDB host them for you on the [Starter tier](https://cortexdb.ai/pricing).
-
-Each connector pulls from a third-party system (Slack, GitHub, Jira, …) and writes every event into CortexDB as a v1 experience.
-
-## Install
-
-```bash
-# core only — no third-party SDK dependencies
-pip install cortexdb-connectors
-
-# with one source's SDK
-pip install 'cortexdb-connectors[slack]'
-
-# everything
-pip install 'cortexdb-connectors[all]'
-```
-
-Requires Python 3.10+.
-
-## Auth
-
-The connectors talk to the CortexDB v1 API. Two things you need:
-
-- **A PASETO bearer token** (`Authorization: Bearer …`)
-- **An actor id** that matches the token's `sub` claim (`X-Cortex-Actor: …`)
-
-The fastest way to get both is to install [`cortexdb-cli`](https://pypi.org/project/cortexdb-cli/) and run `cortexdb init` — anonymous signup, no email or card, 7-day free-tier token. The connectors read `~/.cortexdb/state.json` automatically.
-
-Or set env vars:
-
-```bash
-export CORTEXDB_URL=https://api-v1.cortexdb.ai
-export CORTEXDB_API_KEY=v4.public...
-export CORTEXDB_ACTOR=user:u_019e...
-export CORTEXDB_SCOPE_TEMPLATE='org:acme/source:{source}'   # optional
-```
-
-`{source}` (and `{tenant}`, `{namespace}`, `{actor}`, `{entity.<type>}`) get filled in per event.
-
-## Run
-
-```bash
-# one shot
-cortexdb-sync sync slack
-
-# poll loop, 60s between cycles
-cortexdb-sync watch slack --interval 60
-
-# resume from a specific point
-cortexdb-sync sync github --since 2026-05-01T00:00:00Z
-
-# see what's available
-cortexdb-sync list
-
-# check resolved CortexDB creds
-cortexdb-sync auth
-
-# cursor state across every connector
-cortexdb-sync status
-```
-
-## Available connectors
-
-```
-slack            SLACK_BOT_TOKEN
-github           GITHUB_TOKEN
-gitlab           GITLAB_TOKEN
-jira             JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN
-linear           LINEAR_API_KEY
-confluence       CONFLUENCE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN
-notion           NOTION_TOKEN
-pagerduty        PAGERDUTY_API_KEY
-discord          DISCORD_BOT_TOKEN
-teams            TEAMS_TENANT_ID, TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET
-google-workspace GW_SERVICE_ACCOUNT_KEY, GW_DELEGATED_USER
-salesforce       SF_INSTANCE_URL, SF_CLIENT_ID, SF_CLIENT_SECRET, SF_USERNAME, SF_PASSWORD
-hubspot          HUBSPOT_TOKEN
-zendesk          ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_TOKEN
-intercom         INTERCOM_TOKEN
-servicenow       SNOW_INSTANCE, SNOW_USERNAME, SNOW_PASSWORD
-```
-
-Per-connector setup pages live at https://cortexdb.ai/docs/connectors/ (e.g. [Slack](https://cortexdb.ai/docs/connectors/slack)).
-
-## YAML config
-
-If env vars get unwieldy, drop a `cortexdb-connectors.yaml` next to your sync invocation:
-
-```yaml
-slack:
-  slack_bot_token: xoxb-...
-  channels: [C01ABCDEF, C02GHIJKL]
-
-github:
-  github_token: ghp_...
-  repos: [acme/api, acme/web]
-  events: [pull_request, issue_comment]
-```
-
-## Programmatic use
-
-Skip the CLI entirely:
-
-```python
-import asyncio
-from cortexdb_connectors.slack import SlackConnector
-
-connector = SlackConnector(
-    cortex_url="https://api-v1.cortexdb.ai",
-    cortex_api_key="v4.public...",
-    actor="user:u_019e...",
-    scope_template="org:acme/source:slack/channel:{entity.channel}",
-    slack_bot_token="xoxb-...",
-    channels=["C01ABC", "C02DEF"],
-)
-
-result = asyncio.run(connector.sync())
-print(result.episodes_ingested, "ingested,", len(result.errors), "errors")
-```
-
-## Webhooks
-
-The `cortexdb-connectors[webhooks]` extra ships a Starlette-based webhook receiver for sources that push (Slack Events API, GitHub Apps, Jira webhooks, …) instead of polling. See `cortexdb_connectors/webhooks.py`.
-
-## License
-
-Apache-2.0
+# cortexdb-connectors
+
+Managed data connectors for [CortexDB](https://cortexdb.ai). Run them yourself, or let CortexDB host them for you on the [Starter tier](https://cortexdb.ai/pricing).
+
+Each connector pulls from a third-party system (Slack, GitHub, Jira, …) and writes every event into CortexDB as a v1 experience.
+
+## Plan availability (audit BLK-3)
+
+| Mode | Plan | What it means |
+|---|---|---|
+| **Self-hosted** (`cortexdb-sync` CLI) | 🟢 **Free** (this package) | You run the poller / webhook receiver yourself. Cursor state lives in `~/.cortexdb/`. Every connector below works in this mode. |
+| **Managed sync** (dashboard) | 🔒 **Starter+** ($29/mo) | CortexDB hosts the syncer, manages credentials, and surfaces health in the dashboard. The "Add Connector" button in the dashboard is gated on this plan. |
+
+The free self-hosted path is always available; the managed dashboard path is what the pricing page calls "Starter+". The badge below appears on each connector's setup page for the same reason.
+
+## Install
+
+```bash
+# core only — no third-party SDK dependencies
+pip install cortexdb-connectors
+
+# with one source's SDK
+pip install 'cortexdb-connectors[slack]'
+
+# everything
+pip install 'cortexdb-connectors[all]'
+```
+
+Requires Python 3.10+.
+
+## Auth
+
+The connectors talk to the CortexDB v1 API. Two things you need:
+
+- **A PASETO bearer token** (`Authorization: Bearer …`)
+- **An actor id** that matches the token's `sub` claim (`X-Cortex-Actor: …`)
+
+The fastest way to get both is to install [`cortexdb-cli`](https://pypi.org/project/cortexdb-cli/) and run `cortexdb init` — anonymous signup, no email or card, 7-day free-tier token. The connectors read `~/.cortexdb/state.json` automatically.
+
+Or set env vars:
+
+```bash
+export CORTEXDB_URL=https://api-v1.cortexdb.ai
+export CORTEXDB_API_KEY=v4.public...
+export CORTEXDB_ACTOR=user:u_019e...
+export CORTEXDB_SCOPE_TEMPLATE='org:acme/source:{source}'   # optional
+```
+
+`{source}` (and `{scope}`, `{namespace}`, `{actor}`, `{entity.<type>}`) get filled in per event. (`{tenant}` is still accepted as a legacy alias of `{scope}`.)
+
+## Run
+
+```bash
+# one shot
+cortexdb-sync sync slack
+
+# poll loop, 60s between cycles
+cortexdb-sync watch slack --interval 60
+
+# resume from a specific point
+cortexdb-sync sync github --since 2026-05-01T00:00:00Z
+
+# see what's available
+cortexdb-sync list
+
+# check resolved CortexDB creds
+cortexdb-sync auth
+
+# cursor state across every connector
+cortexdb-sync status
+```
+
+## Available connectors
+
+All 16 connectors are **🟢 Free** to self-host and **🔒 Starter+** ($29/mo) to use via the managed dashboard.
+
+```
+slack            SLACK_BOT_TOKEN
+github           GITHUB_TOKEN
+gitlab           GITLAB_TOKEN
+jira             JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN
+linear           LINEAR_API_KEY
+confluence       CONFLUENCE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN
+notion           NOTION_TOKEN
+pagerduty        PAGERDUTY_API_KEY
+discord          DISCORD_BOT_TOKEN
+teams            TEAMS_TENANT_ID, TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET
+google-workspace GW_SERVICE_ACCOUNT_KEY, GW_DELEGATED_USER
+salesforce       SF_INSTANCE_URL, SF_CLIENT_ID, SF_CLIENT_SECRET, SF_USERNAME, SF_PASSWORD
+hubspot          HUBSPOT_TOKEN
+zendesk          ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_TOKEN
+intercom         INTERCOM_TOKEN
+servicenow       SNOW_INSTANCE, SNOW_USERNAME, SNOW_PASSWORD
+```
+
+Per-connector setup pages live at https://cortexdb.ai/docs/connectors/ (e.g. [Slack](https://cortexdb.ai/docs/connectors/slack)). **The "Add Connector" button on those pages is the managed (Starter+) path** — the CLI on this page is the free path.
+
+For deep self-hosted operation — auth lifetimes, cursor state, retries, OAuth setup for Salesforce/Teams/Google Workspace — see [`SELF_HOSTING.md`](./SELF_HOSTING.md) in this directory.
+
+## YAML config
+
+If env vars get unwieldy, drop a `cortexdb-connectors.yaml` next to your sync invocation:
+
+```yaml
+slack:
+  slack_bot_token: xoxb-...
+  channels: [C01ABCDEF, C02GHIJKL]
+
+github:
+  github_token: ghp_...
+  repos: [acme/api, acme/web]
+  events: [pull_request, issue_comment]
+```
+
+## Programmatic use
+
+Skip the CLI entirely:
+
+```python
+import asyncio
+from cortexdb_connectors.slack import SlackConnector
+
+connector = SlackConnector(
+    cortex_url="https://api-v1.cortexdb.ai",
+    cortex_api_key="v4.public...",
+    scope="org:acme/source:slack",
+    slack_bot_token="xoxb-...",
+    channels=["C01ABC", "C02DEF"],
+)
+# actor + a richer scope_template are set after construction:
+connector.bind(
+    actor="user:u_019e...",
+    scope_template="org:acme/source:slack/channel:{entity.channel}",
+)
+
+result = asyncio.run(connector.sync())
+print(result.episodes_ingested, "ingested,", len(result.errors), "errors")
+```
+
+## Webhooks
+
+The `cortexdb-connectors[webhooks]` extra ships a Starlette-based webhook receiver for sources that push (Slack Events API, GitHub Apps, Jira webhooks, …) instead of polling. See `cortexdb_connectors/webhooks.py`.
+
+## License
+
+Apache-2.0