284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
41 lines
1.8 KiB
Markdown
41 lines
1.8 KiB
Markdown
# Email Provider Adapters – Developer Guide
|
||
|
||
This document explains how provider-specific adapters (e.g. `GmailAdapter`, `MicrosoftAdapter`) are structured and what **NOT** to do after the Pub/Sub refactor.
|
||
|
||
## Responsibilities
|
||
|
||
| Layer | Responsibilities | Must **not** |
|
||
|-------|------------------|--------------|
|
||
| Adapter (`GmailAdapter.ts`) | • Refresh & cache OAuth tokens <br>• Fetch / send messages <br>• Register or renew **Gmail watch** only | Create / modify Pub/Sub topics or subscriptions |
|
||
| Orchestrator (`configureGmailProvider.ts`) | • One-time call to `setupPubSub` <br>• Calculate standard topic / subscription names <br>• Call `GmailAdapter.registerWebhookSubscription()` | Talk directly to Gmail API for message operations |
|
||
|
||
## Adding / Modifying an Adapter
|
||
|
||
1. **Implement Base Methods** – extend `BaseEmailAdapter` and provide `connect`, `getMessage`, `sendMessage`, etc.
|
||
2. **Implement `registerWebhookSubscription`**
|
||
* For Gmail this calls `gmail.users.watch()`.
|
||
* For Microsoft this calls the Graph `subscriptions` endpoint.
|
||
* Do *not* touch Google Pub/Sub or Azure EventGrid – the orchestrator handles infrastructure.
|
||
3. **Persist any IDs / expiration** into `<vendor>_email_provider_config`.
|
||
|
||
### Example: GmailAdapter.registerWebhookSubscription
|
||
|
||
```ts
|
||
async registerWebhookSubscription() {
|
||
await this.ensureValidToken();
|
||
const { project_id, pubsub_topic_name } = this.config.provider_config;
|
||
const topic = `projects/${project_id}/topics/${pubsub_topic_name}`;
|
||
|
||
await this.gmail.users.watch({
|
||
userId: 'me',
|
||
requestBody: { topicName: topic, labelIds: ['INBOX'] }
|
||
});
|
||
// Save historyId & expiration …
|
||
}
|
||
```
|
||
|
||
## Testing
|
||
|
||
See `development/testing.md` for unit and E2E recipes. The most important unit test is that **no adapter** invokes `setupPubSub`.
|
||
|