@rawdash/connector-aws-ses 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +115 -0
  2. package/dist/index.d.ts +204 -0
  3. package/dist/index.js +830 -0
  4. package/dist/index.js.map +1 -0
  5. package/package.json +44 -0
package/README.md ADDED
@@ -0,0 +1,115 @@
1
+ <!-- This file is generated from connector metadata by scripts/generate-connector-docs.ts. Do not edit by hand. -->
2
+
3
+ # @rawdash/connector-aws-ses
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@rawdash/connector-aws-ses)](https://www.npmjs.com/package/@rawdash/connector-aws-ses)
6
+ [![license](https://img.shields.io/npm/l/@rawdash/connector-aws-ses)](https://github.com/rawdash/rawdash/blob/main/LICENSE)
7
+
8
+ Track Amazon SES transactional email volume, deliverability, and sender reputation as daily metric series, optionally split by configuration set.
9
+
10
+ ## Install
11
+
12
+ ```sh
13
+ npm install @rawdash/connector-aws-ses
14
+ ```
15
+
16
+ ## Authentication
17
+
18
+ SES publishes sending and reputation metrics to the AWS/SES CloudWatch namespace, so this connector reads CloudWatch rather than SES directly. Authenticate with either static IAM access keys or an assumed IAM role (STS). The principal needs `cloudwatch:GetMetricData` in the region your SES account sends from.
19
+
20
+ 1. Create an IAM user or role with a policy granting `cloudwatch:GetMetricData`.
21
+ 2. For static credentials, generate an access key ID and secret access key for that IAM user and store both halves as secrets, then reference them as `accessKeyId: secret("AWS_ACCESS_KEY_ID")` and `secretAccessKey: secret("AWS_SECRET_ACCESS_KEY")`.
22
+ 3. For role assumption, set `roleArn` to the role to assume (and `externalId` if its trust policy requires one); the base credentials must be allowed to `sts:AssumeRole` it.
23
+ 4. Set `region` to the AWS region your SES account sends from, e.g. `us-east-1`.
24
+ 5. To break stats down by configuration set, add a CloudWatch event destination to each set in the SES console and list the set names under `configurationSets`. Open and click metrics require engagement tracking to be enabled on the set.
25
+
26
+ ## Configuration
27
+
28
+ | Field | Type | Required | Description |
29
+ | ------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | `region` | string | Yes | The AWS region whose service endpoint you want to call, e.g. us-east-1. |
31
+ | `accessKeyId` | secret | No | AWS access key ID for an IAM principal with permission to call the relevant service. Use together with the secret access key for static-credential auth. |
32
+ | `secretAccessKey` | secret | No | AWS secret access key paired with the access key ID above. |
33
+ | `roleArn` | string | No | IAM role to assume via STS instead of using static keys. The base credentials (the access key above, or the ambient AWS environment) must be allowed to sts:AssumeRole this role. |
34
+ | `externalId` | string | No | External ID required by the trust policy of the role being assumed. Only used with Role ARN. |
35
+ | `configurationSets` | array | No | SES configuration set names to break email stats down by, in addition to the account-wide totals. Each set must publish its events to CloudWatch (via an event destination). Omit to track account-wide totals only. |
36
+ | `lookbackDays` | number | No | How many days of history to fetch on a full sync. Defaults to 30. |
37
+
38
+ ## Resources
39
+
40
+ - **`ses_email_stats`** _(metric)_ - Daily Amazon SES sending funnel pulled from the AWS/SES CloudWatch namespace. One sample per (day, kind, configuration set); the sample value is the count for that kind. The kind dimension covers sends, deliveries, bounces, complaints, opens, and clicks.
41
+ - Endpoint: `POST / (GetMetricData)`
42
+ - Granularity: daily
43
+ - Dimensions: `kind`, `configurationSet`, `stat`
44
+ - Account-wide totals are always present; per-configuration-set, open, and click samples appear only when the relevant CloudWatch event destination and engagement tracking are configured. Each sync rewrites the samples for its window so finalized counts overwrite earlier ones.
45
+ - **`ses_reputation`** _(metric)_ - Daily account-wide SES sender reputation rates from the AWS/SES CloudWatch namespace. One sample per (day, kind); the value is the rate as a fraction between 0 and 1. The kind dimension is bounce_rate or complaint_rate.
46
+ - Endpoint: `POST / (GetMetricData)`
47
+ - Granularity: daily
48
+ - Dimensions: `kind`, `stat`
49
+ - Reputation rates are account-wide only and are not available per configuration set. Each sync rewrites the samples for its window.
50
+
51
+ ## Example
52
+
53
+ ```ts
54
+ import {
55
+ defineConfig,
56
+ defineDashboard,
57
+ defineMetric,
58
+ secret,
59
+ } from '@rawdash/core';
60
+
61
+ const awsSes = {
62
+ name: 'aws-ses',
63
+ connectorId: 'aws-ses',
64
+ config: {
65
+ region: 'us-east-1',
66
+ accessKeyId: secret('AWS_ACCESS_KEY_ID'),
67
+ secretAccessKey: secret('AWS_SECRET_ACCESS_KEY'),
68
+ lookbackDays: 30,
69
+ },
70
+ };
71
+
72
+ export default defineConfig({
73
+ connectors: [awsSes],
74
+ dashboards: {
75
+ email: defineDashboard({
76
+ widgets: {
77
+ sends_30d: {
78
+ kind: 'stat',
79
+ title: 'Emails sent (last 30d)',
80
+ metric: defineMetric({
81
+ connector: awsSes,
82
+ shape: 'metric',
83
+ name: 'ses_email_stats',
84
+ fn: 'sum',
85
+ filter: [
86
+ { field: 'kind', op: 'eq', value: 'sends' },
87
+ { field: 'configurationSet', op: 'eq', value: 'all' },
88
+ ],
89
+ }),
90
+ },
91
+ },
92
+ }),
93
+ },
94
+ });
95
+ ```
96
+
97
+ ## Rate limits
98
+
99
+ GetMetricData is batched at most 500 metrics per call with NextToken pagination; throttling (Throttling / RequestLimitExceeded / TooManyRequests) is retried with backoff.
100
+
101
+ ## Limitations
102
+
103
+ - Metrics are read from CloudWatch, so they reflect whatever SES publishes there; account-wide Send/Delivery/Bounce/Complaint are always available, while per-configuration-set, Open, and Click metrics require the matching CloudWatch event destination and engagement tracking.
104
+ - Reputation bounce and complaint rates are account-wide only; CloudWatch does not expose them per configuration set.
105
+ - A full sync uses lookbackDays (default 30); a latest sync refetches a short trailing window so finalized counts overwrite earlier estimates.
106
+
107
+ ## Links
108
+
109
+ - [Rawdash docs](https://rawdash.dev/docs/connectors)
110
+ - [Amazon Web Services API docs](https://docs.aws.amazon.com/ses/latest/dg/event-publishing-retrieving-cloudwatch.html)
111
+ - [GitHub](https://github.com/rawdash/rawdash)
112
+
113
+ ## License
114
+
115
+ Apache-2.0
package/dist/index.d.ts ADDED
@@ -0,0 +1,204 @@
1
+ import { BaseAWSConnector, BaseAWSSettings } from '@rawdash/connector-aws-shared';
2
+ import { ConnectorContext, SyncOptions, StorageHandle, SyncResult, ConnectorDoc } from '@rawdash/core';
3
+ import { z } from 'zod';
4
+
5
+ declare const configFields: z.ZodObject<{
6
+ configurationSets: z.ZodOptional<z.ZodArray<z.ZodString>>;
7
+ lookbackDays: z.ZodOptional<z.ZodNumber>;
8
+ region: z.ZodString;
9
+ accessKeyId: z.ZodOptional<z.ZodObject<{
10
+ $secret: z.ZodString;
11
+ }, z.core.$strip>>;
12
+ secretAccessKey: z.ZodOptional<z.ZodObject<{
13
+ $secret: z.ZodString;
14
+ }, z.core.$strip>>;
15
+ roleArn: z.ZodOptional<z.ZodString>;
16
+ externalId: z.ZodOptional<z.ZodString>;
17
+ }, z.core.$strip>;
18
+ declare const doc: ConnectorDoc;
19
+ interface AwsSesSettings extends BaseAWSSettings {
20
+ configurationSets?: readonly string[];
21
+ lookbackDays?: number;
22
+ }
23
+ declare const EMAIL_STATS_METRIC = "ses_email_stats";
24
+ declare const REPUTATION_METRIC = "ses_reputation";
25
+ declare const awsSesResources: {
26
+ readonly ses_email_stats: {
27
+ readonly shape: "metric";
28
+ readonly description: "Daily Amazon SES sending funnel pulled from the AWS/SES CloudWatch namespace. One sample per (day, kind, configuration set); the sample value is the count for that kind. The kind dimension covers sends, deliveries, bounces, complaints, opens, and clicks.";
29
+ readonly endpoint: "POST / (GetMetricData)";
30
+ readonly granularity: "daily";
31
+ readonly notes: "Account-wide totals are always present; per-configuration-set, open, and click samples appear only when the relevant CloudWatch event destination and engagement tracking are configured. Each sync rewrites the samples for its window so finalized counts overwrite earlier ones.";
32
+ readonly dimensions: [{
33
+ readonly name: "kind";
34
+ readonly description: "Which funnel counter the sample measures: sends, deliveries, bounces, complaints, opens, or clicks.";
35
+ }, {
36
+ readonly name: "configurationSet";
37
+ readonly description: "The SES configuration set the sample is scoped to, or \"all\" for account-wide totals.";
38
+ }, {
39
+ readonly name: "stat";
40
+ readonly description: "The CloudWatch statistic used, always Sum for stats.";
41
+ }];
42
+ readonly responses: {
43
+ readonly email_stats: z.ZodObject<{
44
+ MetricDataResults: z.ZodArray<z.ZodObject<{
45
+ Id: z.ZodString;
46
+ Label: z.ZodString;
47
+ Timestamps: z.ZodArray<z.ZodISODateTime>;
48
+ Values: z.ZodArray<z.ZodNumber>;
49
+ StatusCode: z.ZodEnum<{
50
+ Complete: "Complete";
51
+ InternalError: "InternalError";
52
+ PartialData: "PartialData";
53
+ Forbidden: "Forbidden";
54
+ }>;
55
+ }, z.core.$strip>>;
56
+ NextToken: z.ZodOptional<z.ZodString>;
57
+ }, z.core.$strip>;
58
+ };
59
+ };
60
+ readonly ses_reputation: {
61
+ readonly shape: "metric";
62
+ readonly description: "Daily account-wide SES sender reputation rates from the AWS/SES CloudWatch namespace. One sample per (day, kind); the value is the rate as a fraction between 0 and 1. The kind dimension is bounce_rate or complaint_rate.";
63
+ readonly endpoint: "POST / (GetMetricData)";
64
+ readonly granularity: "daily";
65
+ readonly notes: "Reputation rates are account-wide only and are not available per configuration set. Each sync rewrites the samples for its window.";
66
+ readonly dimensions: [{
67
+ readonly name: "kind";
68
+ readonly description: "Which reputation rate the sample measures: bounce_rate or complaint_rate.";
69
+ }, {
70
+ readonly name: "stat";
71
+ readonly description: "The CloudWatch statistic used, always Average for reputation rates.";
72
+ }];
73
+ readonly responses: {
74
+ readonly reputation: z.ZodObject<{
75
+ MetricDataResults: z.ZodArray<z.ZodObject<{
76
+ Id: z.ZodString;
77
+ Label: z.ZodString;
78
+ Timestamps: z.ZodArray<z.ZodISODateTime>;
79
+ Values: z.ZodArray<z.ZodNumber>;
80
+ StatusCode: z.ZodEnum<{
81
+ Complete: "Complete";
82
+ InternalError: "InternalError";
83
+ PartialData: "PartialData";
84
+ Forbidden: "Forbidden";
85
+ }>;
86
+ }, z.core.$strip>>;
87
+ NextToken: z.ZodOptional<z.ZodString>;
88
+ }, z.core.$strip>;
89
+ };
90
+ };
91
+ };
92
+ declare const id = "aws-ses";
93
+ declare class AwsSesConnector extends BaseAWSConnector<AwsSesSettings> {
94
+ static readonly id = "aws-ses";
95
+ static readonly resources: {
96
+ readonly ses_email_stats: {
97
+ readonly shape: "metric";
98
+ readonly description: "Daily Amazon SES sending funnel pulled from the AWS/SES CloudWatch namespace. One sample per (day, kind, configuration set); the sample value is the count for that kind. The kind dimension covers sends, deliveries, bounces, complaints, opens, and clicks.";
99
+ readonly endpoint: "POST / (GetMetricData)";
100
+ readonly granularity: "daily";
101
+ readonly notes: "Account-wide totals are always present; per-configuration-set, open, and click samples appear only when the relevant CloudWatch event destination and engagement tracking are configured. Each sync rewrites the samples for its window so finalized counts overwrite earlier ones.";
102
+ readonly dimensions: [{
103
+ readonly name: "kind";
104
+ readonly description: "Which funnel counter the sample measures: sends, deliveries, bounces, complaints, opens, or clicks.";
105
+ }, {
106
+ readonly name: "configurationSet";
107
+ readonly description: "The SES configuration set the sample is scoped to, or \"all\" for account-wide totals.";
108
+ }, {
109
+ readonly name: "stat";
110
+ readonly description: "The CloudWatch statistic used, always Sum for stats.";
111
+ }];
112
+ readonly responses: {
113
+ readonly email_stats: z.ZodObject<{
114
+ MetricDataResults: z.ZodArray<z.ZodObject<{
115
+ Id: z.ZodString;
116
+ Label: z.ZodString;
117
+ Timestamps: z.ZodArray<z.ZodISODateTime>;
118
+ Values: z.ZodArray<z.ZodNumber>;
119
+ StatusCode: z.ZodEnum<{
120
+ Complete: "Complete";
121
+ InternalError: "InternalError";
122
+ PartialData: "PartialData";
123
+ Forbidden: "Forbidden";
124
+ }>;
125
+ }, z.core.$strip>>;
126
+ NextToken: z.ZodOptional<z.ZodString>;
127
+ }, z.core.$strip>;
128
+ };
129
+ };
130
+ readonly ses_reputation: {
131
+ readonly shape: "metric";
132
+ readonly description: "Daily account-wide SES sender reputation rates from the AWS/SES CloudWatch namespace. One sample per (day, kind); the value is the rate as a fraction between 0 and 1. The kind dimension is bounce_rate or complaint_rate.";
133
+ readonly endpoint: "POST / (GetMetricData)";
134
+ readonly granularity: "daily";
135
+ readonly notes: "Reputation rates are account-wide only and are not available per configuration set. Each sync rewrites the samples for its window.";
136
+ readonly dimensions: [{
137
+ readonly name: "kind";
138
+ readonly description: "Which reputation rate the sample measures: bounce_rate or complaint_rate.";
139
+ }, {
140
+ readonly name: "stat";
141
+ readonly description: "The CloudWatch statistic used, always Average for reputation rates.";
142
+ }];
143
+ readonly responses: {
144
+ readonly reputation: z.ZodObject<{
145
+ MetricDataResults: z.ZodArray<z.ZodObject<{
146
+ Id: z.ZodString;
147
+ Label: z.ZodString;
148
+ Timestamps: z.ZodArray<z.ZodISODateTime>;
149
+ Values: z.ZodArray<z.ZodNumber>;
150
+ StatusCode: z.ZodEnum<{
151
+ Complete: "Complete";
152
+ InternalError: "InternalError";
153
+ PartialData: "PartialData";
154
+ Forbidden: "Forbidden";
155
+ }>;
156
+ }, z.core.$strip>>;
157
+ NextToken: z.ZodOptional<z.ZodString>;
158
+ }, z.core.$strip>;
159
+ };
160
+ };
161
+ };
162
+ static readonly schemas: {
163
+ readonly email_stats: z.ZodObject<{
164
+ MetricDataResults: z.ZodArray<z.ZodObject<{
165
+ Id: z.ZodString;
166
+ Label: z.ZodString;
167
+ Timestamps: z.ZodArray<z.ZodISODateTime>;
168
+ Values: z.ZodArray<z.ZodNumber>;
169
+ StatusCode: z.ZodEnum<{
170
+ Complete: "Complete";
171
+ InternalError: "InternalError";
172
+ PartialData: "PartialData";
173
+ Forbidden: "Forbidden";
174
+ }>;
175
+ }, z.core.$strip>>;
176
+ NextToken: z.ZodOptional<z.ZodString>;
177
+ }, z.core.$strip>;
178
+ } & {
179
+ readonly reputation: z.ZodObject<{
180
+ MetricDataResults: z.ZodArray<z.ZodObject<{
181
+ Id: z.ZodString;
182
+ Label: z.ZodString;
183
+ Timestamps: z.ZodArray<z.ZodISODateTime>;
184
+ Values: z.ZodArray<z.ZodNumber>;
185
+ StatusCode: z.ZodEnum<{
186
+ Complete: "Complete";
187
+ InternalError: "InternalError";
188
+ PartialData: "PartialData";
189
+ Forbidden: "Forbidden";
190
+ }>;
191
+ }, z.core.$strip>>;
192
+ NextToken: z.ZodOptional<z.ZodString>;
193
+ }, z.core.$strip>;
194
+ } & Readonly<Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
195
+ static create(input: unknown, ctx?: ConnectorContext): AwsSesConnector;
196
+ readonly id = "aws-ses";
197
+ private planQueries;
198
+ private computeWindow;
199
+ private buildGetMetricDataBody;
200
+ sync(options: SyncOptions, storage: StorageHandle, signal?: AbortSignal): Promise<SyncResult>;
201
+ private collectSamples;
202
+ }
203
+
204
+ export { AwsSesConnector, type AwsSesSettings, EMAIL_STATS_METRIC, REPUTATION_METRIC, configFields, AwsSesConnector as default, doc, id, awsSesResources as resources };