@ever-works/mastodon-connector-plugin 1.0.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.
- package/README.md +48 -0
- package/dist/index.cjs +480 -0
- package/dist/index.d.cts +154 -0
- package/dist/index.d.ts +154 -0
- package/dist/index.js +466 -0
- package/package.json +114 -0
package/README.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# @ever-works/mastodon-connector-plugin
|
|
2
|
+
|
|
3
|
+
First-party **Mastodon social connector** for the Ever Works platform, built on
|
|
4
|
+
the [`masto`](https://www.npmjs.com/package/masto) SDK (Mastodon ships no
|
|
5
|
+
first-party JavaScript SDK; `masto` is the established client — the connector
|
|
6
|
+
never hand-rolls REST calls).
|
|
7
|
+
|
|
8
|
+
Capabilities: `connector`, `connector-mastodon`, `event-source`.
|
|
9
|
+
|
|
10
|
+
## What it does
|
|
11
|
+
|
|
12
|
+
- **Outbound** — `send()` publishes a status at the configured visibility, or a
|
|
13
|
+
threaded reply when the target config carries `inReplyToId`. Idempotent on
|
|
14
|
+
`messageRef`.
|
|
15
|
+
- **Event source** — `pullEvents()` sweeps notifications (mentions, favourites,
|
|
16
|
+
boosts, follows) and then the connected account's own statuses, normalized
|
|
17
|
+
into `IngestedEventEnvelope`s (`mastodon.notification` / `mastodon.status`)
|
|
18
|
+
for the event-ingest spine. Status HTML is flattened to plain text; the
|
|
19
|
+
status permalink rides along as `sourceUrl`. Mastodon paginates by id, so
|
|
20
|
+
each phase walks `max_id` newest-first and stops at the first item older than
|
|
21
|
+
the watermark.
|
|
22
|
+
- **Opt-in historical backfill** — `backfillDays` (default `0` = off, max 90)
|
|
23
|
+
widens the FIRST pull's window only, bounded to
|
|
24
|
+
`MASTODON_BACKFILL_MAX_PAGES` pages per phase.
|
|
25
|
+
|
|
26
|
+
## Degradation is loud, never silent
|
|
27
|
+
|
|
28
|
+
- `verifyConnection()` reports missing credentials, an SSRF-unsafe instance URL,
|
|
29
|
+
and failed credential verification.
|
|
30
|
+
- `send()` throws on missing credentials or a failed status create.
|
|
31
|
+
- `pullEvents()` throws `EventSourceNotConfiguredError` when the instance URL or
|
|
32
|
+
access token is absent, or when the token resolves to no account.
|
|
33
|
+
|
|
34
|
+
## Settings
|
|
35
|
+
|
|
36
|
+
| Key | Notes |
|
|
37
|
+
| ------------------- | -------------------------------------------------------- |
|
|
38
|
+
| `instanceUrl` | Instance base URL — SSRF-guarded before every call. |
|
|
39
|
+
| `accessToken` | Application token — secret, env `MASTODON_ACCESS_TOKEN`. |
|
|
40
|
+
| `defaultVisibility` | `public` \| `unlisted` \| `private` \| `direct`. |
|
|
41
|
+
| `backfillDays` | Opt-in first-pull history window (0 = off, max 90). |
|
|
42
|
+
|
|
43
|
+
No credential is hardcoded, logged, or written into an ingested envelope.
|
|
44
|
+
|
|
45
|
+
## Testing
|
|
46
|
+
|
|
47
|
+
Hermetic Vitest suite (`pnpm test`) — the SDK client is stubbed through the
|
|
48
|
+
`createClient` seam; no network calls.
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +1,480 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, '__esModule', { value: true });
|
|
4
|
+
|
|
5
|
+
var crypto = require('crypto');
|
|
6
|
+
var masto = require('masto');
|
|
7
|
+
require('@ever-works/contracts');
|
|
8
|
+
var net = require('net');
|
|
9
|
+
|
|
10
|
+
// src/mastodon-connector-plugin.ts
|
|
11
|
+
var EventSourceNotConfiguredError = class extends Error {
|
|
12
|
+
constructor(message) {
|
|
13
|
+
super(message ?? "Event-source plugin is not configured in this runtime.");
|
|
14
|
+
this.name = "EventSourceNotConfiguredError";
|
|
15
|
+
}
|
|
16
|
+
};
|
|
17
|
+
var PLUGIN_CAPABILITIES = {
|
|
18
|
+
// Connectors ("Connector fabric") — first-party BIDIRECTIONAL
|
|
19
|
+
// communication-channel plugins. Each connector declares `CONNECTOR`
|
|
20
|
+
// (umbrella, for discovery/grouping) plus its `CONNECTOR_<provider>`
|
|
21
|
+
// constant. Superset of the outbound-only notification channels; see
|
|
22
|
+
// `capabilities/connector.interface.ts`.
|
|
23
|
+
CONNECTOR: "connector",
|
|
24
|
+
CONNECTOR_MASTODON: "connector-mastodon",
|
|
25
|
+
// Event-ingest spine (Wave 6) — plugins that pull/push normalized
|
|
26
|
+
// external events into the platform ingest pipeline. See
|
|
27
|
+
// capabilities/event-source.interface.ts.
|
|
28
|
+
EVENT_SOURCE: "event-source"};
|
|
29
|
+
function isSafeWebhookUrl(rawUrl) {
|
|
30
|
+
let url;
|
|
31
|
+
try {
|
|
32
|
+
url = new URL(rawUrl);
|
|
33
|
+
} catch {
|
|
34
|
+
return false;
|
|
35
|
+
}
|
|
36
|
+
if (url.protocol !== "https:" && url.protocol !== "http:") {
|
|
37
|
+
return false;
|
|
38
|
+
}
|
|
39
|
+
let host = url.hostname.toLowerCase();
|
|
40
|
+
if (host.startsWith("[") && host.endsWith("]")) {
|
|
41
|
+
host = host.slice(1, -1);
|
|
42
|
+
}
|
|
43
|
+
if (CLOUD_METADATA_HOSTNAMES.has(host)) {
|
|
44
|
+
return false;
|
|
45
|
+
}
|
|
46
|
+
const ipKind = net.isIP(host);
|
|
47
|
+
if (ipKind === 4 && isPrivateIPv4(host)) return false;
|
|
48
|
+
if (ipKind === 6 && isPrivateIPv6(host)) return false;
|
|
49
|
+
return true;
|
|
50
|
+
}
|
|
51
|
+
var CLOUD_METADATA_HOSTNAMES = /* @__PURE__ */ new Set([
|
|
52
|
+
// GCP
|
|
53
|
+
"metadata.google.internal",
|
|
54
|
+
"metadata.goog",
|
|
55
|
+
// AWS
|
|
56
|
+
"instance-data",
|
|
57
|
+
"instance-data.ec2.internal",
|
|
58
|
+
// Azure
|
|
59
|
+
"metadata.azure.internal"
|
|
60
|
+
]);
|
|
61
|
+
function isPrivateIPv4(ip) {
|
|
62
|
+
const parts = ip.split(".").map((p) => Number(p));
|
|
63
|
+
if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return false;
|
|
64
|
+
const [a, b] = parts;
|
|
65
|
+
if (a === 10) return true;
|
|
66
|
+
if (a === 127) return true;
|
|
67
|
+
if (a === 0) return true;
|
|
68
|
+
if (a === 169 && b === 254) return true;
|
|
69
|
+
if (a === 172 && b >= 16 && b <= 31) return true;
|
|
70
|
+
if (a === 192 && b === 168) return true;
|
|
71
|
+
if (a === 192 && b === 0 && parts[2] === 0) return true;
|
|
72
|
+
if (a === 100 && b >= 64 && b <= 127) return true;
|
|
73
|
+
if (a >= 224) return true;
|
|
74
|
+
return false;
|
|
75
|
+
}
|
|
76
|
+
function isPrivateIPv6(ip) {
|
|
77
|
+
const lower = ip.toLowerCase();
|
|
78
|
+
if (lower === "::1" || lower === "::") return true;
|
|
79
|
+
if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
|
|
80
|
+
const firstHextet = lower.split(":", 1)[0];
|
|
81
|
+
if (/^[0-9a-f]{1,4}$/.test(firstHextet)) {
|
|
82
|
+
const group0 = parseInt(firstHextet, 16);
|
|
83
|
+
if ((group0 & 65472) === 65152) return true;
|
|
84
|
+
}
|
|
85
|
+
if (lower.startsWith("::ffff:")) {
|
|
86
|
+
const v4 = lower.slice("::ffff:".length);
|
|
87
|
+
if (net.isIP(v4) === 4) return isPrivateIPv4(v4);
|
|
88
|
+
}
|
|
89
|
+
return false;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
// src/mastodon-connector-plugin.ts
|
|
93
|
+
var MASTODON_EVENT_TEXT_MAX_CHARS = 4e3;
|
|
94
|
+
var MASTODON_PULL_PAGE_SIZE = 40;
|
|
95
|
+
var MASTODON_BACKFILL_MAX_PAGES = 10;
|
|
96
|
+
var MASTODON_VISIBILITIES = ["public", "unlisted", "private", "direct"];
|
|
97
|
+
function clampBackfillDays(value) {
|
|
98
|
+
const num = typeof value === "number" ? value : Number(value);
|
|
99
|
+
if (!Number.isFinite(num) || num <= 0) return 0;
|
|
100
|
+
return Math.min(Math.floor(num), 90);
|
|
101
|
+
}
|
|
102
|
+
function truncateText(text) {
|
|
103
|
+
return text.length > MASTODON_EVENT_TEXT_MAX_CHARS ? text.slice(0, MASTODON_EVENT_TEXT_MAX_CHARS) : text;
|
|
104
|
+
}
|
|
105
|
+
function stripStatusHtml(html) {
|
|
106
|
+
if (typeof html !== "string" || html.length === 0) return void 0;
|
|
107
|
+
const text = html.replace(/<br\s*\/?>/gi, "\n").replace(/<\/p>/gi, "\n\n").replace(/<[^>]+>/g, "").replace(/ /g, " ").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, '"').replace(/'/g, "'").replace(/&/g, "&").trim();
|
|
108
|
+
return text.length > 0 ? text : void 0;
|
|
109
|
+
}
|
|
110
|
+
function resolveVisibility(value) {
|
|
111
|
+
if (typeof value === "string") {
|
|
112
|
+
const candidate = value.trim().toLowerCase();
|
|
113
|
+
if (MASTODON_VISIBILITIES.includes(candidate)) {
|
|
114
|
+
return candidate;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
return "public";
|
|
118
|
+
}
|
|
119
|
+
function mastodonErrorMessage(err) {
|
|
120
|
+
const e = err;
|
|
121
|
+
return e.message ?? e.error ?? (typeof e.statusCode === "number" ? `HTTP ${e.statusCode}` : "unknown error");
|
|
122
|
+
}
|
|
123
|
+
function toIso(value) {
|
|
124
|
+
if (value instanceof Date) return value.toISOString();
|
|
125
|
+
if (typeof value === "string") {
|
|
126
|
+
const ms = Date.parse(value);
|
|
127
|
+
if (Number.isFinite(ms)) return new Date(ms).toISOString();
|
|
128
|
+
}
|
|
129
|
+
return (/* @__PURE__ */ new Date(0)).toISOString();
|
|
130
|
+
}
|
|
131
|
+
function parsePullCursor(cursor) {
|
|
132
|
+
if (!cursor) return void 0;
|
|
133
|
+
try {
|
|
134
|
+
const parsed = JSON.parse(cursor);
|
|
135
|
+
if (parsed && (parsed.p === "notifications" || parsed.p === "statuses") && typeof parsed.s === "string") {
|
|
136
|
+
return parsed;
|
|
137
|
+
}
|
|
138
|
+
} catch {
|
|
139
|
+
}
|
|
140
|
+
return void 0;
|
|
141
|
+
}
|
|
142
|
+
function firstString(candidates) {
|
|
143
|
+
for (const c of candidates) {
|
|
144
|
+
if (typeof c === "string" && c.trim().length > 0) return c.trim();
|
|
145
|
+
}
|
|
146
|
+
return void 0;
|
|
147
|
+
}
|
|
148
|
+
function resolveCredentials(config, options) {
|
|
149
|
+
const instanceUrl = firstString([config.instanceUrl, options.settings?.instanceUrl]);
|
|
150
|
+
const accessToken = firstString([config.accessToken, options.settings?.accessToken]);
|
|
151
|
+
if (!instanceUrl || !accessToken) return void 0;
|
|
152
|
+
return { instanceUrl, accessToken };
|
|
153
|
+
}
|
|
154
|
+
var MastodonConnectorPlugin = class {
|
|
155
|
+
constructor() {
|
|
156
|
+
this.id = "mastodon-connector";
|
|
157
|
+
this.name = "Mastodon Connector";
|
|
158
|
+
this.version = "1.0.0";
|
|
159
|
+
this.category = "connector";
|
|
160
|
+
this.capabilities = [
|
|
161
|
+
PLUGIN_CAPABILITIES.CONNECTOR,
|
|
162
|
+
PLUGIN_CAPABILITIES.CONNECTOR_MASTODON,
|
|
163
|
+
PLUGIN_CAPABILITIES.EVENT_SOURCE
|
|
164
|
+
];
|
|
165
|
+
this.providerName = "mastodon";
|
|
166
|
+
this.connector = {
|
|
167
|
+
direction: "outbound",
|
|
168
|
+
transport: "poll",
|
|
169
|
+
flags: {
|
|
170
|
+
outboundMessage: true,
|
|
171
|
+
outboundRecord: false,
|
|
172
|
+
inbound: false,
|
|
173
|
+
reply: false,
|
|
174
|
+
pairing: false,
|
|
175
|
+
richOutbound: false
|
|
176
|
+
}
|
|
177
|
+
};
|
|
178
|
+
this.settingsSchema = {
|
|
179
|
+
type: "object",
|
|
180
|
+
required: ["instanceUrl", "accessToken"],
|
|
181
|
+
properties: {
|
|
182
|
+
instanceUrl: {
|
|
183
|
+
type: "string",
|
|
184
|
+
title: "Mastodon instance URL (e.g. https://mastodon.social)"
|
|
185
|
+
},
|
|
186
|
+
accessToken: {
|
|
187
|
+
type: "string",
|
|
188
|
+
title: "Mastodon application access token",
|
|
189
|
+
"x-secret": true,
|
|
190
|
+
"x-envVar": "MASTODON_ACCESS_TOKEN"
|
|
191
|
+
},
|
|
192
|
+
defaultVisibility: {
|
|
193
|
+
type: "string",
|
|
194
|
+
title: "Visibility applied to outbound statuses",
|
|
195
|
+
default: "public",
|
|
196
|
+
enum: [...MASTODON_VISIBILITIES]
|
|
197
|
+
},
|
|
198
|
+
backfillDays: {
|
|
199
|
+
type: "number",
|
|
200
|
+
title: "Historical backfill window in days on first pull (0 = off, max 90)",
|
|
201
|
+
default: 0,
|
|
202
|
+
minimum: 0,
|
|
203
|
+
maximum: 90
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
};
|
|
207
|
+
this.idempotencyCache = /* @__PURE__ */ new Map();
|
|
208
|
+
}
|
|
209
|
+
async onLoad() {
|
|
210
|
+
}
|
|
211
|
+
async onUnload() {
|
|
212
|
+
this.idempotencyCache.clear();
|
|
213
|
+
}
|
|
214
|
+
/** Testable seam — specs stub this; production uses the real SDK. */
|
|
215
|
+
createClient(instanceUrl, accessToken) {
|
|
216
|
+
return masto.createRestAPIClient({ url: instanceUrl, accessToken });
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Build a client for the operator's instance. The instance URL is
|
|
220
|
+
* user-supplied, so it passes the shared SSRF guard before any
|
|
221
|
+
* request is issued.
|
|
222
|
+
*/
|
|
223
|
+
connect(credentials) {
|
|
224
|
+
if (!isSafeWebhookUrl(credentials.instanceUrl)) {
|
|
225
|
+
throw new Error(`mastodon-connector: refusing to use an unsafe instance URL '${credentials.instanceUrl}'`);
|
|
226
|
+
}
|
|
227
|
+
return this.createClient(credentials.instanceUrl, credentials.accessToken);
|
|
228
|
+
}
|
|
229
|
+
async verifyConnection(config, options) {
|
|
230
|
+
const credentials = resolveCredentials(config, options);
|
|
231
|
+
if (!credentials) {
|
|
232
|
+
return { valid: false, message: "instanceUrl and accessToken are required" };
|
|
233
|
+
}
|
|
234
|
+
try {
|
|
235
|
+
const account = await this.connect(credentials).v1.accounts.verifyCredentials();
|
|
236
|
+
return {
|
|
237
|
+
valid: true,
|
|
238
|
+
details: {
|
|
239
|
+
instanceUrl: credentials.instanceUrl,
|
|
240
|
+
...account?.id ? { accountId: account.id } : {},
|
|
241
|
+
...account?.acct ? { acct: account.acct } : {},
|
|
242
|
+
...account?.displayName ? { displayName: account.displayName } : {}
|
|
243
|
+
}
|
|
244
|
+
};
|
|
245
|
+
} catch (err) {
|
|
246
|
+
return { valid: false, message: `Mastodon verifyCredentials failed: ${mastodonErrorMessage(err)}` };
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
/** Outbound leg — publish a status (or a threaded reply). */
|
|
250
|
+
async send(payload, options) {
|
|
251
|
+
const config = payload.target ?? options.target ?? {};
|
|
252
|
+
const credentials = resolveCredentials(config, options);
|
|
253
|
+
if (!credentials) {
|
|
254
|
+
throw new Error(
|
|
255
|
+
"mastodon-connector: instanceUrl and accessToken are required (targetConfig.instanceUrl/accessToken or settings.instanceUrl/accessToken)"
|
|
256
|
+
);
|
|
257
|
+
}
|
|
258
|
+
const inReplyToId = firstString([config.inReplyToId]);
|
|
259
|
+
const visibility = resolveVisibility(config.visibility ?? options.settings?.defaultVisibility);
|
|
260
|
+
const cacheKey = `${options.connectorId ?? ""}\0${inReplyToId ?? ""}\0${payload.messageRef}`;
|
|
261
|
+
const cached = this.idempotencyCache.get(cacheKey);
|
|
262
|
+
if (cached) return cached;
|
|
263
|
+
let statusId;
|
|
264
|
+
try {
|
|
265
|
+
const status = await this.connect(credentials).v1.statuses.create({
|
|
266
|
+
status: payload.text,
|
|
267
|
+
visibility,
|
|
268
|
+
...inReplyToId ? { inReplyToId } : {}
|
|
269
|
+
});
|
|
270
|
+
statusId = typeof status?.id === "string" ? status.id : void 0;
|
|
271
|
+
} catch (err) {
|
|
272
|
+
throw new Error(`Mastodon status create failed: ${mastodonErrorMessage(err)}`);
|
|
273
|
+
}
|
|
274
|
+
const result = {
|
|
275
|
+
provider: this.id,
|
|
276
|
+
providerMessageId: statusId ?? `mastodon-${payload.messageRef}`,
|
|
277
|
+
deliveredAt: /* @__PURE__ */ new Date()
|
|
278
|
+
};
|
|
279
|
+
this.idempotencyCache.set(cacheKey, result);
|
|
280
|
+
if (this.idempotencyCache.size > 500) {
|
|
281
|
+
const firstKey = this.idempotencyCache.keys().next().value;
|
|
282
|
+
if (firstKey) this.idempotencyCache.delete(firstKey);
|
|
283
|
+
}
|
|
284
|
+
return result;
|
|
285
|
+
}
|
|
286
|
+
// ── Event source (pull) ─────────────────────────────────────────────
|
|
287
|
+
/**
|
|
288
|
+
* Pull one page of the current sweep phase (notifications → own
|
|
289
|
+
* statuses) since the effective watermark, normalized to envelopes.
|
|
290
|
+
* The returned cursor resumes the same phase (Mastodon `max_id`) or
|
|
291
|
+
* advances to the next; no cursor means the sweep is done.
|
|
292
|
+
*
|
|
293
|
+
* First pull (epoch/absent watermark, no cursor): the window is
|
|
294
|
+
* `now - backfillDays` when the opt-in backfill is on, otherwise
|
|
295
|
+
* `now` — history stays untouched unless the user asked for it.
|
|
296
|
+
*/
|
|
297
|
+
async pullEvents(input) {
|
|
298
|
+
const instanceUrl = input.settings?.instanceUrl;
|
|
299
|
+
const accessToken = input.settings?.accessToken;
|
|
300
|
+
if (typeof instanceUrl !== "string" || instanceUrl.length === 0) {
|
|
301
|
+
throw new EventSourceNotConfiguredError(
|
|
302
|
+
"mastodon-connector: settings.instanceUrl is required to pull events"
|
|
303
|
+
);
|
|
304
|
+
}
|
|
305
|
+
if (typeof accessToken !== "string" || accessToken.length === 0) {
|
|
306
|
+
throw new EventSourceNotConfiguredError(
|
|
307
|
+
"mastodon-connector: settings.accessToken is required to pull events"
|
|
308
|
+
);
|
|
309
|
+
}
|
|
310
|
+
const cursor = parsePullCursor(input.cursor);
|
|
311
|
+
let phase;
|
|
312
|
+
let maxId;
|
|
313
|
+
let since;
|
|
314
|
+
let backfill;
|
|
315
|
+
let pagesUsed;
|
|
316
|
+
if (cursor) {
|
|
317
|
+
phase = cursor.p;
|
|
318
|
+
maxId = cursor.n;
|
|
319
|
+
since = cursor.s;
|
|
320
|
+
backfill = cursor.f === 1;
|
|
321
|
+
pagesUsed = cursor.b ?? 0;
|
|
322
|
+
} else {
|
|
323
|
+
const sinceMs2 = Date.parse(input.since);
|
|
324
|
+
const firstPull = !Number.isFinite(sinceMs2) || sinceMs2 <= 0;
|
|
325
|
+
const backfillDays = clampBackfillDays(input.settings?.backfillDays);
|
|
326
|
+
if (firstPull) {
|
|
327
|
+
const start = backfillDays > 0 ? Date.now() - backfillDays * 864e5 : Date.now();
|
|
328
|
+
since = new Date(start).toISOString();
|
|
329
|
+
backfill = backfillDays > 0;
|
|
330
|
+
} else {
|
|
331
|
+
since = new Date(sinceMs2).toISOString();
|
|
332
|
+
backfill = false;
|
|
333
|
+
}
|
|
334
|
+
phase = "notifications";
|
|
335
|
+
maxId = void 0;
|
|
336
|
+
pagesUsed = 0;
|
|
337
|
+
}
|
|
338
|
+
const client = this.connect({ instanceUrl, accessToken });
|
|
339
|
+
const sinceMs = Date.parse(since);
|
|
340
|
+
const events = [];
|
|
341
|
+
let lastId;
|
|
342
|
+
let pageSize = 0;
|
|
343
|
+
let stopSweep = false;
|
|
344
|
+
if (phase === "notifications") {
|
|
345
|
+
const notifications = await client.v1.notifications.list({
|
|
346
|
+
limit: MASTODON_PULL_PAGE_SIZE,
|
|
347
|
+
...maxId ? { maxId } : {}
|
|
348
|
+
});
|
|
349
|
+
pageSize = notifications.length;
|
|
350
|
+
for (const notification of notifications) {
|
|
351
|
+
lastId = notification.id ?? lastId;
|
|
352
|
+
const createdMs = Date.parse(notification.createdAt ?? "");
|
|
353
|
+
if (Number.isFinite(createdMs) && createdMs < sinceMs) {
|
|
354
|
+
stopSweep = true;
|
|
355
|
+
break;
|
|
356
|
+
}
|
|
357
|
+
const envelope = this.normalizeNotification(notification);
|
|
358
|
+
if (envelope) events.push(envelope);
|
|
359
|
+
}
|
|
360
|
+
} else {
|
|
361
|
+
const account = await client.v1.accounts.verifyCredentials();
|
|
362
|
+
const accountId = account?.id;
|
|
363
|
+
if (!accountId) {
|
|
364
|
+
throw new EventSourceNotConfiguredError(
|
|
365
|
+
"mastodon-connector: the access token resolved to no account \u2014 re-authorize the application"
|
|
366
|
+
);
|
|
367
|
+
}
|
|
368
|
+
const statuses = await client.v1.accounts.$select(accountId).statuses.list({
|
|
369
|
+
limit: MASTODON_PULL_PAGE_SIZE,
|
|
370
|
+
...maxId ? { maxId } : {}
|
|
371
|
+
});
|
|
372
|
+
pageSize = statuses.length;
|
|
373
|
+
for (const status of statuses) {
|
|
374
|
+
lastId = status.id ?? lastId;
|
|
375
|
+
const createdMs = Date.parse(status.createdAt ?? "");
|
|
376
|
+
if (Number.isFinite(createdMs) && createdMs < sinceMs) {
|
|
377
|
+
stopSweep = true;
|
|
378
|
+
break;
|
|
379
|
+
}
|
|
380
|
+
const envelope = this.normalizeStatus(status);
|
|
381
|
+
if (envelope) events.push(envelope);
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
pagesUsed += 1;
|
|
385
|
+
const pageBudgetExhausted = backfill && pagesUsed >= MASTODON_BACKFILL_MAX_PAGES;
|
|
386
|
+
const mayHaveMore = pageSize >= MASTODON_PULL_PAGE_SIZE && lastId !== void 0;
|
|
387
|
+
let next;
|
|
388
|
+
if (!stopSweep && mayHaveMore && !pageBudgetExhausted) {
|
|
389
|
+
next = { p: phase, n: lastId, s: since, ...backfill ? { f: 1 } : {}, b: pagesUsed };
|
|
390
|
+
} else if (phase === "notifications") {
|
|
391
|
+
next = { p: "statuses", s: since, ...backfill ? { f: 1 } : {}, b: 0 };
|
|
392
|
+
}
|
|
393
|
+
return next ? { events, nextCursor: JSON.stringify(next) } : { events };
|
|
394
|
+
}
|
|
395
|
+
normalizeNotification(notification) {
|
|
396
|
+
if (!notification.id) return null;
|
|
397
|
+
const occurredAt = toIso(notification.createdAt);
|
|
398
|
+
const type = notification.type ?? "unknown";
|
|
399
|
+
const account = notification.account ?? {};
|
|
400
|
+
const text = stripStatusHtml(notification.status?.content);
|
|
401
|
+
const sourceUrl = notification.status?.url ?? account.url;
|
|
402
|
+
return {
|
|
403
|
+
id: crypto.randomUUID(),
|
|
404
|
+
source: this.id,
|
|
405
|
+
sourceEventId: `notification:${notification.id}`,
|
|
406
|
+
kind: "mastodon.notification",
|
|
407
|
+
occurredAt,
|
|
408
|
+
...account.acct || account.displayName ? {
|
|
409
|
+
actor: {
|
|
410
|
+
name: account.displayName ?? account.acct ?? "unknown",
|
|
411
|
+
...account.id ? { externalId: account.id } : {}
|
|
412
|
+
}
|
|
413
|
+
} : {},
|
|
414
|
+
subject: {
|
|
415
|
+
type: notification.status?.id ? "status" : "account",
|
|
416
|
+
externalId: notification.status?.id ?? account.id ?? notification.id,
|
|
417
|
+
...text ? { title: truncateText(text) } : {}
|
|
418
|
+
},
|
|
419
|
+
...sourceUrl ? { sourceUrl } : {},
|
|
420
|
+
payload: {
|
|
421
|
+
notificationType: type,
|
|
422
|
+
notificationId: notification.id,
|
|
423
|
+
...notification.status?.id ? { statusId: notification.status.id } : {},
|
|
424
|
+
...account.id ? { accountId: account.id } : {},
|
|
425
|
+
...account.acct ? { acct: account.acct } : {},
|
|
426
|
+
...text ? { text: truncateText(text) } : {},
|
|
427
|
+
createdAt: occurredAt
|
|
428
|
+
}
|
|
429
|
+
};
|
|
430
|
+
}
|
|
431
|
+
normalizeStatus(status) {
|
|
432
|
+
if (!status.id) return null;
|
|
433
|
+
const occurredAt = toIso(status.createdAt);
|
|
434
|
+
const account = status.account ?? {};
|
|
435
|
+
const text = stripStatusHtml(status.content);
|
|
436
|
+
return {
|
|
437
|
+
id: crypto.randomUUID(),
|
|
438
|
+
source: this.id,
|
|
439
|
+
sourceEventId: `status:${status.id}`,
|
|
440
|
+
kind: "mastodon.status",
|
|
441
|
+
occurredAt,
|
|
442
|
+
...account.acct || account.displayName ? {
|
|
443
|
+
actor: {
|
|
444
|
+
name: account.displayName ?? account.acct ?? "unknown",
|
|
445
|
+
...account.id ? { externalId: account.id } : {}
|
|
446
|
+
}
|
|
447
|
+
} : {},
|
|
448
|
+
subject: {
|
|
449
|
+
type: "status",
|
|
450
|
+
externalId: status.id,
|
|
451
|
+
...text ? { title: truncateText(text) } : {}
|
|
452
|
+
},
|
|
453
|
+
...status.url ? { sourceUrl: status.url } : {},
|
|
454
|
+
payload: {
|
|
455
|
+
statusId: status.id,
|
|
456
|
+
...status.uri ? { uri: status.uri } : {},
|
|
457
|
+
...status.visibility ? { visibility: status.visibility } : {},
|
|
458
|
+
...account.acct ? { acct: account.acct } : {},
|
|
459
|
+
...text ? { text: truncateText(text) } : {},
|
|
460
|
+
...typeof status.repliesCount === "number" ? { repliesCount: status.repliesCount } : {},
|
|
461
|
+
...typeof status.reblogsCount === "number" ? { reblogsCount: status.reblogsCount } : {},
|
|
462
|
+
...typeof status.favouritesCount === "number" ? { favouritesCount: status.favouritesCount } : {},
|
|
463
|
+
createdAt: occurredAt
|
|
464
|
+
}
|
|
465
|
+
};
|
|
466
|
+
}
|
|
467
|
+
};
|
|
468
|
+
var mastodonConnectorPlugin = new MastodonConnectorPlugin();
|
|
469
|
+
|
|
470
|
+
exports.MASTODON_BACKFILL_MAX_PAGES = MASTODON_BACKFILL_MAX_PAGES;
|
|
471
|
+
exports.MASTODON_EVENT_TEXT_MAX_CHARS = MASTODON_EVENT_TEXT_MAX_CHARS;
|
|
472
|
+
exports.MASTODON_PULL_PAGE_SIZE = MASTODON_PULL_PAGE_SIZE;
|
|
473
|
+
exports.MASTODON_VISIBILITIES = MASTODON_VISIBILITIES;
|
|
474
|
+
exports.MastodonConnectorPlugin = MastodonConnectorPlugin;
|
|
475
|
+
exports.clampBackfillDays = clampBackfillDays;
|
|
476
|
+
exports.default = MastodonConnectorPlugin;
|
|
477
|
+
exports.mastodonConnectorPlugin = mastodonConnectorPlugin;
|
|
478
|
+
exports.resolveCredentials = resolveCredentials;
|
|
479
|
+
exports.resolveVisibility = resolveVisibility;
|
|
480
|
+
exports.stripStatusHtml = stripStatusHtml;
|
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
import { IConnectorPlugin, IEventSourcePlugin, PluginCategory, ConnectorMetadata, JsonSchema, ChannelTargetConfig, ConnectorCallOptions, ChannelVerification, ChannelSendInput, ChannelSendResult, EventSourcePullInput, EventSourcePullResult } from '@ever-works/plugin';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Payload text cap for ingested envelopes. Envelope payloads are
|
|
5
|
+
* size-capped platform-side (32 KB serialized); a status body never
|
|
6
|
+
* needs more than this to be useful in Memory/Activities.
|
|
7
|
+
*/
|
|
8
|
+
declare const MASTODON_EVENT_TEXT_MAX_CHARS = 4000;
|
|
9
|
+
/** Items requested per Mastodon page (notifications and statuses alike). */
|
|
10
|
+
declare const MASTODON_PULL_PAGE_SIZE = 40;
|
|
11
|
+
/**
|
|
12
|
+
* Historical backfill bound: at most this many pages per phase
|
|
13
|
+
* (notifications, then the account's own statuses) during the opt-in
|
|
14
|
+
* first-pull backfill, so a busy account can never turn activation
|
|
15
|
+
* into an unbounded crawl.
|
|
16
|
+
*/
|
|
17
|
+
declare const MASTODON_BACKFILL_MAX_PAGES = 10;
|
|
18
|
+
/** Visibilities Mastodon accepts for an outbound status. */
|
|
19
|
+
declare const MASTODON_VISIBILITIES: readonly ["public", "unlisted", "private", "direct"];
|
|
20
|
+
type MastodonVisibility = (typeof MASTODON_VISIBILITIES)[number];
|
|
21
|
+
/** Clamp the opt-in backfill window to the supported 0–90 day range. */
|
|
22
|
+
declare function clampBackfillDays(value: unknown): number;
|
|
23
|
+
/**
|
|
24
|
+
* Mastodon status bodies are HTML. Envelopes carry plain text (Memory
|
|
25
|
+
* observations and Activity rows are text surfaces), so block-level
|
|
26
|
+
* markup becomes newlines, remaining tags are dropped and the handful
|
|
27
|
+
* of entities Mastodon actually emits are decoded.
|
|
28
|
+
*/
|
|
29
|
+
declare function stripStatusHtml(html: string | undefined): string | undefined;
|
|
30
|
+
/** Normalize the configured visibility, defaulting to `public`. */
|
|
31
|
+
declare function resolveVisibility(value: unknown): MastodonVisibility;
|
|
32
|
+
/** Minimal shape of an account we consume. */
|
|
33
|
+
interface MastodonAccount {
|
|
34
|
+
id?: string;
|
|
35
|
+
username?: string;
|
|
36
|
+
acct?: string;
|
|
37
|
+
displayName?: string;
|
|
38
|
+
url?: string;
|
|
39
|
+
}
|
|
40
|
+
/** Minimal shape of a status we consume. */
|
|
41
|
+
interface MastodonStatus {
|
|
42
|
+
id?: string;
|
|
43
|
+
uri?: string;
|
|
44
|
+
url?: string;
|
|
45
|
+
content?: string;
|
|
46
|
+
createdAt?: string;
|
|
47
|
+
repliesCount?: number;
|
|
48
|
+
reblogsCount?: number;
|
|
49
|
+
favouritesCount?: number;
|
|
50
|
+
visibility?: string;
|
|
51
|
+
account?: MastodonAccount;
|
|
52
|
+
}
|
|
53
|
+
/** Minimal shape of a notification we consume. */
|
|
54
|
+
interface MastodonNotification {
|
|
55
|
+
id?: string;
|
|
56
|
+
type?: string;
|
|
57
|
+
createdAt?: string;
|
|
58
|
+
account?: MastodonAccount;
|
|
59
|
+
status?: MastodonStatus;
|
|
60
|
+
}
|
|
61
|
+
/** The subset of the `masto` REST surface this plugin calls. */
|
|
62
|
+
interface MastodonClientLike {
|
|
63
|
+
v1: {
|
|
64
|
+
accounts: {
|
|
65
|
+
verifyCredentials(): Promise<MastodonAccount>;
|
|
66
|
+
$select(id: string): {
|
|
67
|
+
statuses: {
|
|
68
|
+
list(params: Record<string, unknown>): Promise<MastodonStatus[]>;
|
|
69
|
+
};
|
|
70
|
+
};
|
|
71
|
+
};
|
|
72
|
+
statuses: {
|
|
73
|
+
create(params: Record<string, unknown>): Promise<MastodonStatus>;
|
|
74
|
+
};
|
|
75
|
+
notifications: {
|
|
76
|
+
list(params: Record<string, unknown>): Promise<MastodonNotification[]>;
|
|
77
|
+
};
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
/** Resolved credentials for one call. */
|
|
81
|
+
interface MastodonCredentials {
|
|
82
|
+
instanceUrl: string;
|
|
83
|
+
accessToken: string;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Resolve credentials from the per-connection target config, falling
|
|
87
|
+
* back to the resolved plugin settings. Returns undefined (never a
|
|
88
|
+
* partial) so callers fail loudly with one clear message.
|
|
89
|
+
*/
|
|
90
|
+
declare function resolveCredentials(config: ChannelTargetConfig, options: ConnectorCallOptions): MastodonCredentials | undefined;
|
|
91
|
+
/**
|
|
92
|
+
* Mastodon social connector — first-party native connector.
|
|
93
|
+
*
|
|
94
|
+
* Outbound: `send` publishes a status — or a threaded reply when the
|
|
95
|
+
* target config carries `inReplyToId` — through the `masto` SDK against
|
|
96
|
+
* the operator's own instance. The instance URL is operator-supplied,
|
|
97
|
+
* so it passes the shared SSRF guard before any request is issued.
|
|
98
|
+
*
|
|
99
|
+
* Event source: `pullEvents` sweeps notifications (mentions, favourites,
|
|
100
|
+
* boosts, follows) then the connected account's own statuses since the
|
|
101
|
+
* watermark, normalized into `IngestedEventEnvelope`s
|
|
102
|
+
* (`mastodon.notification` / `mastodon.status`, the status permalink as
|
|
103
|
+
* `sourceUrl`) for the platform's event-ingest spine. Mastodon paginates
|
|
104
|
+
* by id rather than time, so each phase walks `max_id` newest-first and
|
|
105
|
+
* stops at the first item older than the watermark. The opt-in
|
|
106
|
+
* historical backfill (`backfillDays`, default 0 = off, max 90) widens
|
|
107
|
+
* the FIRST pull's window only, with a per-phase page bound.
|
|
108
|
+
* Re-delivery across overlapping windows is fine — the ingest pipeline
|
|
109
|
+
* dedupes on `(source, sourceEventId)`.
|
|
110
|
+
*
|
|
111
|
+
* Unconfigured is always LOUD: `verifyConnection` reports the missing
|
|
112
|
+
* credentials, `send` throws, and `pullEvents` throws
|
|
113
|
+
* `EventSourceNotConfiguredError`. Nothing silently no-ops.
|
|
114
|
+
*/
|
|
115
|
+
declare class MastodonConnectorPlugin implements IConnectorPlugin, IEventSourcePlugin {
|
|
116
|
+
readonly id = "mastodon-connector";
|
|
117
|
+
readonly name = "Mastodon Connector";
|
|
118
|
+
readonly version = "1.0.0";
|
|
119
|
+
readonly category: PluginCategory;
|
|
120
|
+
readonly capabilities: readonly ["connector", "connector-mastodon", "event-source"];
|
|
121
|
+
readonly providerName = "mastodon";
|
|
122
|
+
readonly connector: ConnectorMetadata;
|
|
123
|
+
readonly settingsSchema: JsonSchema;
|
|
124
|
+
private readonly idempotencyCache;
|
|
125
|
+
onLoad(): Promise<void>;
|
|
126
|
+
onUnload(): Promise<void>;
|
|
127
|
+
/** Testable seam — specs stub this; production uses the real SDK. */
|
|
128
|
+
protected createClient(instanceUrl: string, accessToken: string): MastodonClientLike;
|
|
129
|
+
/**
|
|
130
|
+
* Build a client for the operator's instance. The instance URL is
|
|
131
|
+
* user-supplied, so it passes the shared SSRF guard before any
|
|
132
|
+
* request is issued.
|
|
133
|
+
*/
|
|
134
|
+
private connect;
|
|
135
|
+
verifyConnection(config: ChannelTargetConfig, options: ConnectorCallOptions): Promise<ChannelVerification>;
|
|
136
|
+
/** Outbound leg — publish a status (or a threaded reply). */
|
|
137
|
+
send(payload: ChannelSendInput, options: ConnectorCallOptions): Promise<ChannelSendResult>;
|
|
138
|
+
/**
|
|
139
|
+
* Pull one page of the current sweep phase (notifications → own
|
|
140
|
+
* statuses) since the effective watermark, normalized to envelopes.
|
|
141
|
+
* The returned cursor resumes the same phase (Mastodon `max_id`) or
|
|
142
|
+
* advances to the next; no cursor means the sweep is done.
|
|
143
|
+
*
|
|
144
|
+
* First pull (epoch/absent watermark, no cursor): the window is
|
|
145
|
+
* `now - backfillDays` when the opt-in backfill is on, otherwise
|
|
146
|
+
* `now` — history stays untouched unless the user asked for it.
|
|
147
|
+
*/
|
|
148
|
+
pullEvents(input: EventSourcePullInput): Promise<EventSourcePullResult>;
|
|
149
|
+
private normalizeNotification;
|
|
150
|
+
private normalizeStatus;
|
|
151
|
+
}
|
|
152
|
+
declare const mastodonConnectorPlugin: MastodonConnectorPlugin;
|
|
153
|
+
|
|
154
|
+
export { MASTODON_BACKFILL_MAX_PAGES, MASTODON_EVENT_TEXT_MAX_CHARS, MASTODON_PULL_PAGE_SIZE, MASTODON_VISIBILITIES, MastodonConnectorPlugin, type MastodonVisibility, clampBackfillDays, MastodonConnectorPlugin as default, mastodonConnectorPlugin, resolveCredentials, resolveVisibility, stripStatusHtml };
|