@respectify/astro 0.1.8 → 0.2.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 +54 -0
- package/components/CommentSection.astro +7 -4
- package/default-respectify.config.json +1 -0
- package/package.json +8 -5
- package/respectify.config.sample.jsonc +47 -5
- package/src/actions.ts +20 -1
- package/src/credentials.ts +1 -0
- package/src/index.ts +15 -0
- package/src/lib/config.ts +60 -0
- package/src/lib/rate-limit.ts +24 -0
- package/src/lib/service.ts +84 -29
- package/src/runtime-config.ts +5 -1
- package/src/types.ts +40 -3
package/README.md
CHANGED
|
@@ -180,6 +180,14 @@ respectify({
|
|
|
180
180
|
commentsApiPath: '/api/respectify/comments',
|
|
181
181
|
showBranding: true,
|
|
182
182
|
getPostUrl: (slug, site) => `${site}/posts/${slug}/`,
|
|
183
|
+
|
|
184
|
+
// Alternative to getPostUrl: hand Respectify the post body directly instead of
|
|
185
|
+
// having it fetch getPostUrl. Useful for staged/preview/auth-gated content, or
|
|
186
|
+
// when the URL isn't live yet right after deploy. Takes priority over getPostUrl.
|
|
187
|
+
// getPostContent: async (slug) => loadPostBody(slug),
|
|
188
|
+
|
|
189
|
+
// Per-IP submission limit, enforced in the `comments.submit` action.
|
|
190
|
+
// In-memory per server process — not shared across multiple instances/regions.
|
|
183
191
|
rateLimit: { windowMs: 300_000, maxRequests: 10 },
|
|
184
192
|
|
|
185
193
|
// Forwarded to RespectifyClient (email/apiKey still default from env)
|
|
@@ -200,9 +208,25 @@ respectify({
|
|
|
200
208
|
sensitiveTopics: [],
|
|
201
209
|
dogwhistleExamples: [],
|
|
202
210
|
},
|
|
211
|
+
|
|
212
|
+
// Comment-health tolerances sent with every megacall, merged per item over the
|
|
213
|
+
// JSON config's `tolerances` (these win). See "Comment health and tolerances" below.
|
|
214
|
+
tolerances: { insult: 'relaxed', threat: 'zero_tolerance', quality: 'strict' },
|
|
203
215
|
});
|
|
204
216
|
```
|
|
205
217
|
|
|
218
|
+
`showBranding` and `commentsApiPath` set here become the defaults for `<CommentSection>` — you can still override either per-instance via props.
|
|
219
|
+
|
|
220
|
+
### Checking Respectify credentials
|
|
221
|
+
|
|
222
|
+
```ts
|
|
223
|
+
import { verifyRespectifyCredentials } from '@respectify/astro/credentials';
|
|
224
|
+
|
|
225
|
+
const isConnected = await verifyRespectifyCredentials();
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Useful for an admin health-check page — returns `true` when `RESPECTIFY_EMAIL`/`RESPECTIFY_API_KEY` (or `client.email`/`client.apiKey`) are valid and the subscription is active.
|
|
229
|
+
|
|
206
230
|
### `respectify.config.json`
|
|
207
231
|
|
|
208
232
|
Moderation policy lives in the JSON file. You can also put `client` / `megacall` there (same shapes as above). Integration options win on conflicts.
|
|
@@ -211,6 +235,36 @@ For a field-by-field walkthrough with comments, see [`respectify.config.sample.j
|
|
|
211
235
|
|
|
212
236
|
Replies automatically pass the parent comment text as `replyToComment` to Respectify.
|
|
213
237
|
|
|
238
|
+
### Comment health and tolerances
|
|
239
|
+
|
|
240
|
+
Comment health has ten items: the nine problem categories and `quality`. `tolerances` (in `respectify.config.json` or the integration options) sets a level per item; items not named are `standard`. Nothing is stored on the API key.
|
|
241
|
+
|
|
242
|
+
```json
|
|
243
|
+
{
|
|
244
|
+
"tolerances": { "insult": "relaxed", "profanity": "off", "threat": "zero_tolerance", "quality": "strict" }
|
|
245
|
+
}
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
- Items: `threat`, `identity_attack`, `sexual_content`, `harassment`, `insult`, `profanity`, `dismissive_tone`, `logical_fallacy`, `low_effort`, `quality`
|
|
249
|
+
- Levels, loosest to strictest: `off`, `permissive`, `relaxed`, `standard` (default), `strict`, `zero_tolerance`
|
|
250
|
+
- A problem category fails on its worst finding (severity 1 minor, 2 clear, 3 severe, 4 extreme): `permissive` filters only the very worst, failing extreme findings alone; `relaxed` fails severe and extreme findings; `standard` fails clear, severe and extreme ones; `strict` and `zero_tolerance` fail any. `quality` sets the lowest 1-5 quality score accepted: `permissive` and `relaxed` 2, `standard` 3, `strict` 4, `zero_tolerance` 5. `off` leaves the item out of comment health.
|
|
251
|
+
- `threat`, `identity_attack`, `sexual_content` and `harassment` are floored: they can be made stricter but never `permissive`, `relaxed` or `off`. The config fails to load if you try (and the integration throws at setup for the `tolerances` option).
|
|
252
|
+
|
|
253
|
+
Tolerances shape the comment score, so they are only sent when a comment score runs (which needs topic context). When the API returns them, the analysis result carries `healthScore` (1.0-5.0) and `healthItems` (per item: `score`, `minimum`, `is_acceptable`).
|
|
254
|
+
|
|
255
|
+
### How comments are approved, warned or blocked
|
|
256
|
+
|
|
257
|
+
Spam, off-topic (`blockOffTopic`) and dogwhistle (`blockDogwhistles`) rejections come first. Suspected spam is not spam: the comment is sent back to the commenter (never approved, even with `allowOverride`) with the server's suggestion as `feedback`, such as "This looks like spam. How about removing the link?", while any comment-health coaching stays in `suggestion`. The analysis result carries `suspectedSpam` and `spamSuggestion` (and `isSpam: false`) whenever a spam check ran; `suspectedSpam` is `false` when an older API omits it, and the `comments.submit` action returns `suspectedSpam` for a comment it did not publish. Then, on content:
|
|
258
|
+
|
|
259
|
+
| Comment score says | Respectfulness (`1 - toxicity_score`) | Result |
|
|
260
|
+
| --- | --- | --- |
|
|
261
|
+
| `exceeds_tolerance: false` | any | Approved (`feedback.approved`) |
|
|
262
|
+
| `exceeds_tolerance: true` | `< thresholds.block` and `blockDisrespectful` | Blocked (`feedback.blocked`) |
|
|
263
|
+
| `exceeds_tolerance: true` | otherwise | Warning (`feedback.warning`), approved only when `allowOverride` |
|
|
264
|
+
| no comment score | — | Approved |
|
|
265
|
+
|
|
266
|
+
`exceeds_tolerance` decides whether a comment has a problem at all, because it reflects your site's comment-health tolerances (any item below its minimum, or severe toxicity); `toxicity_score` does not, so it only chooses between warning and blocking. `thresholds.autoApprove` applies only when the API returns a comment score without `exceeds_tolerance` (an API older than tolerances), where the previous bands are used. The returned `exceedsTolerance` field carries the verdict.
|
|
267
|
+
|
|
214
268
|
### Admin delete (optional)
|
|
215
269
|
|
|
216
270
|
Set `enableDelete` on `CommentSection` and implement auth so `context.locals.isAuthenticated` is true. See the [Nick-Blog](https://github.com/NickHodges/Nick-Blog) repo for a full admin auth example.
|
|
@@ -3,13 +3,14 @@ import '@respectify/astro/styles.css';
|
|
|
3
3
|
import PoweredByRespectify from './PoweredByRespectify.astro';
|
|
4
4
|
import CommentList from './CommentList.astro';
|
|
5
5
|
import CommentForm from './CommentForm.astro';
|
|
6
|
+
import { getIntegrationOptions } from '../src/runtime-config';
|
|
6
7
|
|
|
7
8
|
interface Props {
|
|
8
9
|
/** Unique identifier for the page/post (e.g. blog slug) */
|
|
9
10
|
postSlug: string;
|
|
10
|
-
/** API path
|
|
11
|
+
/** API path (default: the integration's `commentsApiPath` option) */
|
|
11
12
|
apiPath?: string;
|
|
12
|
-
/** Show Powered by Respectify branding (default:
|
|
13
|
+
/** Show Powered by Respectify branding (default: the integration's `showBranding` option) */
|
|
13
14
|
showBranding?: boolean;
|
|
14
15
|
/** Enable admin delete controls when authenticated (default: false) */
|
|
15
16
|
enableDelete?: boolean;
|
|
@@ -19,10 +20,12 @@ interface Props {
|
|
|
19
20
|
style?: string;
|
|
20
21
|
}
|
|
21
22
|
|
|
23
|
+
const integrationOptions = getIntegrationOptions();
|
|
24
|
+
|
|
22
25
|
const {
|
|
23
26
|
postSlug,
|
|
24
|
-
apiPath =
|
|
25
|
-
showBranding =
|
|
27
|
+
apiPath = integrationOptions.commentsApiPath,
|
|
28
|
+
showBranding = integrationOptions.showBranding,
|
|
26
29
|
enableDelete = false,
|
|
27
30
|
class: className,
|
|
28
31
|
style,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@respectify/astro",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Respectify-powered commenting for Astro — AI moderation, spam filtering, and beautiful UX out of the box.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -30,6 +30,7 @@
|
|
|
30
30
|
"exports": {
|
|
31
31
|
".": "./src/index.ts",
|
|
32
32
|
"./actions": "./src/actions.ts",
|
|
33
|
+
"./credentials": "./src/credentials.ts",
|
|
33
34
|
"./schema": "./src/schema.ts",
|
|
34
35
|
"./routes/comments": "./src/routes/comments.ts",
|
|
35
36
|
"./components/CommentSection.astro": "./components/CommentSection.astro",
|
|
@@ -47,7 +48,7 @@
|
|
|
47
48
|
],
|
|
48
49
|
"peerDependencies": {
|
|
49
50
|
"@astrojs/db": "^0.20.0",
|
|
50
|
-
"@respectify/client": "^0.
|
|
51
|
+
"@respectify/client": "^0.7.0",
|
|
51
52
|
"astro": "^5.0.0 || ^6.0.0",
|
|
52
53
|
"zod": "^3.0.0"
|
|
53
54
|
},
|
|
@@ -60,12 +61,14 @@
|
|
|
60
61
|
"zod": "^3.24.0"
|
|
61
62
|
},
|
|
62
63
|
"scripts": {
|
|
63
|
-
"typecheck": "tsc --noEmit"
|
|
64
|
+
"typecheck": "tsc --noEmit",
|
|
65
|
+
"test": "vitest run"
|
|
64
66
|
},
|
|
65
67
|
"devDependencies": {
|
|
66
68
|
"@astrojs/db": "^0.20.0",
|
|
67
|
-
"@respectify/client": "^0.
|
|
69
|
+
"@respectify/client": "^0.7.0",
|
|
68
70
|
"astro": "^6.0.4",
|
|
69
|
-
"typescript": "^5.4.3"
|
|
71
|
+
"typescript": "^5.4.3",
|
|
72
|
+
"vitest": "^3.2.4"
|
|
70
73
|
}
|
|
71
74
|
}
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
// rateLimit: { windowMs: 300_000, maxRequests: 10 },
|
|
26
26
|
// client: { /* same shape as "client" below */ },
|
|
27
27
|
// megacall: { /* same shape as "megacall" below */ },
|
|
28
|
+
// tolerances: { /* same shape as "tolerances" below; wins per item */ },
|
|
28
29
|
// })
|
|
29
30
|
//
|
|
30
31
|
// =============================================================================
|
|
@@ -89,15 +90,52 @@
|
|
|
89
90
|
// "replyToComment": "Parent comment text"
|
|
90
91
|
},
|
|
91
92
|
|
|
93
|
+
// ---------------------------------------------------------------------------
|
|
94
|
+
// tolerances — comment health: how much of each item this site accepts
|
|
95
|
+
// Ten items: the nine problem categories below, plus "quality". Items not
|
|
96
|
+
// named are "standard". Sent only when a comment score runs.
|
|
97
|
+
//
|
|
98
|
+
// Levels, loosest to strictest:
|
|
99
|
+
// "off" | "permissive" | "relaxed" | "standard" (default) | "strict" | "zero_tolerance"
|
|
100
|
+
// Problem categories, by their worst finding (minor, clear, severe, extreme):
|
|
101
|
+
// permissive filters only the very worst (fails extreme only), relaxed fails
|
|
102
|
+
// severe and extreme, standard fails clear and worse, strict and
|
|
103
|
+
// zero_tolerance fail any.
|
|
104
|
+
// Quality, the lowest 1-5 score accepted: permissive and relaxed 2,
|
|
105
|
+
// standard 3, strict 4, zero_tolerance 5. "off" leaves the item out of
|
|
106
|
+
// comment health entirely.
|
|
107
|
+
// threat, identity_attack, sexual_content and harassment are floored: they
|
|
108
|
+
// can be made stricter but never "permissive", "relaxed" or "off" (the config
|
|
109
|
+
// fails to load).
|
|
110
|
+
// ---------------------------------------------------------------------------
|
|
111
|
+
"tolerances": {
|
|
112
|
+
// Floored categories: "standard" | "strict" | "zero_tolerance"
|
|
113
|
+
// "threat": "zero_tolerance",
|
|
114
|
+
// "identity_attack": "strict",
|
|
115
|
+
// "sexual_content": "strict",
|
|
116
|
+
// "harassment": "strict",
|
|
117
|
+
|
|
118
|
+
// Tunable categories: any level, including "permissive", "relaxed" and "off"
|
|
119
|
+
// "insult": "relaxed",
|
|
120
|
+
// "profanity": "off",
|
|
121
|
+
// "dismissive_tone": "standard",
|
|
122
|
+
// "logical_fallacy": "relaxed",
|
|
123
|
+
// "low_effort": "strict",
|
|
124
|
+
|
|
125
|
+
// Quality: any level
|
|
126
|
+
// "quality": "strict"
|
|
127
|
+
},
|
|
128
|
+
|
|
92
129
|
// ---------------------------------------------------------------------------
|
|
93
130
|
// moderation — how megacall results become approve / reject decisions
|
|
94
131
|
// ---------------------------------------------------------------------------
|
|
95
132
|
"moderation": {
|
|
96
|
-
//
|
|
133
|
+
// When the comment score says exceeds_tolerance, block it if its
|
|
134
|
+
// respectfulness score is below `thresholds.block`
|
|
97
135
|
"blockDisrespectful": true,
|
|
98
136
|
|
|
99
|
-
//
|
|
100
|
-
// `feedback.warning
|
|
137
|
+
// A comment that exceeds tolerance but is not blocked gets
|
|
138
|
+
// `feedback.warning`; allow it through when true, reject when false
|
|
101
139
|
"allowOverride": false,
|
|
102
140
|
|
|
103
141
|
// Include revision suggestions (toxicity explanation, fallacies, etc.)
|
|
@@ -116,15 +154,19 @@
|
|
|
116
154
|
// ---------------------------------------------------------------------------
|
|
117
155
|
// thresholds — respectfulness score bands (0.0–1.0)
|
|
118
156
|
// Score is derived as `1 - toxicity_score` from comment_score when available.
|
|
157
|
+
// comment_score.exceeds_tolerance decides whether a comment has a problem:
|
|
158
|
+
// false → approve, whatever the score. true → the score picks warn or block.
|
|
119
159
|
// ---------------------------------------------------------------------------
|
|
120
160
|
"thresholds": {
|
|
121
|
-
//
|
|
161
|
+
// Only used when the API returns no exceeds_tolerance (older API):
|
|
162
|
+
// score >= this → approve with `feedback.approved`
|
|
122
163
|
"autoApprove": 0.7,
|
|
123
164
|
|
|
124
165
|
// Reserved mid band (kept for compatibility; decisions use autoApprove/block)
|
|
125
166
|
"warn": 0.5,
|
|
126
167
|
|
|
127
|
-
//
|
|
168
|
+
// exceeds_tolerance + score < this + blockDisrespectful → reject with
|
|
169
|
+
// `feedback.blocked`; exceeds_tolerance at or above this → `feedback.warning`
|
|
128
170
|
"block": 0.3
|
|
129
171
|
},
|
|
130
172
|
|
package/src/actions.ts
CHANGED
|
@@ -2,6 +2,8 @@ import { defineAction, ActionError } from 'astro:actions';
|
|
|
2
2
|
import { z } from 'astro/zod';
|
|
3
3
|
import { db, Comment, eq } from 'astro:db';
|
|
4
4
|
import { analyzeComment } from './lib/service';
|
|
5
|
+
import { checkRateLimit } from './lib/rate-limit';
|
|
6
|
+
import { getIntegrationOptions } from './runtime-config';
|
|
5
7
|
|
|
6
8
|
/**
|
|
7
9
|
* Merge into your src/actions/index.ts:
|
|
@@ -25,7 +27,23 @@ export const respectifyCommentActions = {
|
|
|
25
27
|
content: z.string().min(1).max(5000),
|
|
26
28
|
parentId: z.number().optional(),
|
|
27
29
|
}),
|
|
28
|
-
handler: async ({ postSlug, author, email, content, parentId }) => {
|
|
30
|
+
handler: async ({ postSlug, author, email, content, parentId }, context) => {
|
|
31
|
+
const { rateLimit } = getIntegrationOptions();
|
|
32
|
+
if (rateLimit) {
|
|
33
|
+
let key = 'unknown';
|
|
34
|
+
try {
|
|
35
|
+
key = context.clientAddress;
|
|
36
|
+
} catch {
|
|
37
|
+
// Some adapters/rendering modes don't expose a client address; fall back to a shared bucket.
|
|
38
|
+
}
|
|
39
|
+
if (!checkRateLimit(key, rateLimit.windowMs, rateLimit.maxRequests)) {
|
|
40
|
+
throw new ActionError({
|
|
41
|
+
code: 'TOO_MANY_REQUESTS',
|
|
42
|
+
message: 'Too many comments submitted. Please wait a bit before trying again.',
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
|
|
29
47
|
let replyToComment: string | undefined;
|
|
30
48
|
if (parentId !== undefined) {
|
|
31
49
|
const [parent] = await db.select().from(Comment).where(eq(Comment.id, parentId)).limit(1);
|
|
@@ -40,6 +58,7 @@ export const respectifyCommentActions = {
|
|
|
40
58
|
approved: false as const,
|
|
41
59
|
feedback: analysis.feedback,
|
|
42
60
|
suggestion: analysis.suggestion,
|
|
61
|
+
suspectedSpam: analysis.suspectedSpam === true,
|
|
43
62
|
score: analysis.score,
|
|
44
63
|
};
|
|
45
64
|
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { verifyRespectifyCredentials } from './lib/service';
|
package/src/index.ts
CHANGED
|
@@ -1,9 +1,24 @@
|
|
|
1
1
|
import type { AstroIntegration } from 'astro';
|
|
2
2
|
import { envField } from 'astro/config';
|
|
3
|
+
import { RespectifyError, validateModerationTolerances } from '@respectify/client';
|
|
3
4
|
import { setIntegrationOptions } from './runtime-config';
|
|
4
5
|
import type { RespectifyIntegrationOptions } from './types';
|
|
5
6
|
|
|
7
|
+
/** Fail at setup, not on the first comment, when the integration's tolerances are invalid. */
|
|
8
|
+
function assertValidTolerances(userOptions: RespectifyIntegrationOptions): void {
|
|
9
|
+
if (userOptions.tolerances === undefined) return;
|
|
10
|
+
try {
|
|
11
|
+
validateModerationTolerances(userOptions.tolerances);
|
|
12
|
+
} catch (error) {
|
|
13
|
+
if (error instanceof RespectifyError) {
|
|
14
|
+
throw new Error(`Invalid Respectify tolerances: ${error.message}`);
|
|
15
|
+
}
|
|
16
|
+
throw error;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
6
20
|
export default function respectify(userOptions: RespectifyIntegrationOptions = {}): AstroIntegration {
|
|
21
|
+
assertValidTolerances(userOptions);
|
|
7
22
|
setIntegrationOptions(userOptions);
|
|
8
23
|
|
|
9
24
|
const commentsApiPath = userOptions.commentsApiPath ?? '/api/respectify/comments';
|
package/src/lib/config.ts
CHANGED
|
@@ -1,9 +1,57 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
2
|
import fs from 'node:fs';
|
|
3
3
|
import path from 'node:path';
|
|
4
|
+
import { TOLERANCE_LEVELS } from '@respectify/client';
|
|
5
|
+
import type {
|
|
6
|
+
FlooredModerationCategory,
|
|
7
|
+
FlooredToleranceLevel,
|
|
8
|
+
ModerationTolerances,
|
|
9
|
+
ToleranceLevel,
|
|
10
|
+
} from '@respectify/client';
|
|
4
11
|
import { getIntegrationOptions } from '../runtime-config';
|
|
5
12
|
import type { RespectifyClientConfig, RespectifyMegacallConfig } from '../types';
|
|
6
13
|
|
|
14
|
+
/** Levels a floored category accepts: standard or stricter, never permissive, relaxed or off. */
|
|
15
|
+
const FLOORED_TOLERANCE_LEVELS = ['standard', 'strict', 'zero_tolerance'] as const satisfies readonly FlooredToleranceLevel[];
|
|
16
|
+
|
|
17
|
+
const ToleranceLevelSchema = z.enum(TOLERANCE_LEVELS);
|
|
18
|
+
|
|
19
|
+
/** Levels looser than a floored category allows, which get the API's floor wording rather than the default error. */
|
|
20
|
+
const BELOW_FLOOR_TOLERANCE_LEVELS: readonly ToleranceLevel[] = ['off', 'permissive', 'relaxed'];
|
|
21
|
+
|
|
22
|
+
/** A floored category's level, rejecting "permissive", "relaxed" and "off" with the same wording the API uses. */
|
|
23
|
+
function flooredToleranceLevelSchema(
|
|
24
|
+
category: FlooredModerationCategory,
|
|
25
|
+
): z.ZodEnum<z.Writeable<typeof FLOORED_TOLERANCE_LEVELS>> {
|
|
26
|
+
return z.enum(FLOORED_TOLERANCE_LEVELS, {
|
|
27
|
+
errorMap: (_issue, ctx) => ({
|
|
28
|
+
message:
|
|
29
|
+
BELOW_FLOOR_TOLERANCE_LEVELS.includes(ctx.data)
|
|
30
|
+
? `${category} can be made stricter but not relaxed or turned off`
|
|
31
|
+
: ctx.defaultError,
|
|
32
|
+
}),
|
|
33
|
+
});
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Per-site tolerances: a level per comment-health item (the nine problem categories and
|
|
38
|
+
* quality). Items not named are "standard". Unknown items are rejected.
|
|
39
|
+
*/
|
|
40
|
+
const ModerationTolerancesSchema = z
|
|
41
|
+
.object({
|
|
42
|
+
threat: flooredToleranceLevelSchema('threat').optional(),
|
|
43
|
+
identity_attack: flooredToleranceLevelSchema('identity_attack').optional(),
|
|
44
|
+
sexual_content: flooredToleranceLevelSchema('sexual_content').optional(),
|
|
45
|
+
harassment: flooredToleranceLevelSchema('harassment').optional(),
|
|
46
|
+
insult: ToleranceLevelSchema.optional(),
|
|
47
|
+
profanity: ToleranceLevelSchema.optional(),
|
|
48
|
+
dismissive_tone: ToleranceLevelSchema.optional(),
|
|
49
|
+
logical_fallacy: ToleranceLevelSchema.optional(),
|
|
50
|
+
low_effort: ToleranceLevelSchema.optional(),
|
|
51
|
+
quality: ToleranceLevelSchema.optional(),
|
|
52
|
+
})
|
|
53
|
+
.strict() satisfies z.ZodType<ModerationTolerances>;
|
|
54
|
+
|
|
7
55
|
const MegacallConfigSchema = z
|
|
8
56
|
.object({
|
|
9
57
|
includeSpam: z.boolean().optional(),
|
|
@@ -64,6 +112,8 @@ const RespectifyConfigSchema = z.object({
|
|
|
64
112
|
client: ClientConfigSchema,
|
|
65
113
|
/** Options forwarded to megacall (merged with integration `megacall` options) */
|
|
66
114
|
megacall: MegacallConfigSchema,
|
|
115
|
+
/** Moderation tolerances sent with every megacall (merged with integration `tolerances`) */
|
|
116
|
+
tolerances: ModerationTolerancesSchema.optional(),
|
|
67
117
|
});
|
|
68
118
|
|
|
69
119
|
export type RespectifyConfig = z.infer<typeof RespectifyConfigSchema>;
|
|
@@ -110,6 +160,16 @@ export function resolveMegacallConfig(config: RespectifyConfig): RespectifyMegac
|
|
|
110
160
|
};
|
|
111
161
|
}
|
|
112
162
|
|
|
163
|
+
/**
|
|
164
|
+
* Merge JSON + integration tolerances per item. Integration options win.
|
|
165
|
+
* Undefined when neither names an item, so every item is judged at "standard".
|
|
166
|
+
*/
|
|
167
|
+
export function resolveTolerances(config: RespectifyConfig): ModerationTolerances | undefined {
|
|
168
|
+
const { tolerances: integrationTolerances } = getIntegrationOptions();
|
|
169
|
+
const merged: ModerationTolerances = { ...config.tolerances, ...integrationTolerances };
|
|
170
|
+
return Object.keys(merged).length > 0 ? merged : undefined;
|
|
171
|
+
}
|
|
172
|
+
|
|
113
173
|
export function getDefaultConfig(): RespectifyConfig {
|
|
114
174
|
return {
|
|
115
175
|
enabled: true,
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
interface Bucket {
|
|
2
|
+
count: number;
|
|
3
|
+
resetAt: number;
|
|
4
|
+
}
|
|
5
|
+
|
|
6
|
+
const buckets = new Map<string, Bucket>();
|
|
7
|
+
|
|
8
|
+
/** Simple in-memory fixed-window rate limiter, keyed per process (not shared across instances/regions). */
|
|
9
|
+
export function checkRateLimit(key: string, windowMs: number, maxRequests: number): boolean {
|
|
10
|
+
const now = Date.now();
|
|
11
|
+
const bucket = buckets.get(key);
|
|
12
|
+
|
|
13
|
+
if (!bucket || now >= bucket.resetAt) {
|
|
14
|
+
buckets.set(key, { count: 1, resetAt: now + windowMs });
|
|
15
|
+
return true;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
if (bucket.count >= maxRequests) {
|
|
19
|
+
return false;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
bucket.count += 1;
|
|
23
|
+
return true;
|
|
24
|
+
}
|
package/src/lib/service.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { RespectifyConfig } from './config';
|
|
2
|
-
import { loadRespectifyConfig, resolveClientConfig, resolveMegacallConfig } from './config';
|
|
2
|
+
import { loadRespectifyConfig, resolveClientConfig, resolveMegacallConfig, resolveTolerances } from './config';
|
|
3
3
|
import { RESPECTIFY_API_KEY, RESPECTIFY_EMAIL } from 'astro:env/server';
|
|
4
4
|
import {
|
|
5
5
|
RespectifyClient,
|
|
@@ -54,18 +54,22 @@ async function getOrInitializeArticleId(postSlug: string, config: RespectifyConf
|
|
|
54
54
|
const cached = articleIdCache.get(postSlug);
|
|
55
55
|
if (cached) return cached;
|
|
56
56
|
|
|
57
|
-
const { getPostUrl } = getIntegrationOptions();
|
|
58
|
-
const site = import.meta.env.SITE;
|
|
59
|
-
if (!site) {
|
|
60
|
-
throw new Error('import.meta.env.SITE must be set in astro.config.ts for Respectify topic initialization.');
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
const postUrl = getPostUrl!(postSlug, site);
|
|
57
|
+
const { getPostUrl, getPostContent } = getIntegrationOptions();
|
|
64
58
|
const respectifyClient = getRespectifyClient(config);
|
|
59
|
+
const topicDescription = `Post: ${postSlug}`;
|
|
60
|
+
|
|
61
|
+
const result = await (getPostContent
|
|
62
|
+
? respectifyClient.initTopicFromText(await getPostContent(postSlug), topicDescription)
|
|
63
|
+
: (() => {
|
|
64
|
+
const site = import.meta.env.SITE;
|
|
65
|
+
if (!site) {
|
|
66
|
+
throw new Error('import.meta.env.SITE must be set in astro.config.ts for Respectify topic initialization.');
|
|
67
|
+
}
|
|
68
|
+
return respectifyClient.initTopicFromUrl(getPostUrl!(postSlug, site), topicDescription);
|
|
69
|
+
})());
|
|
65
70
|
|
|
66
|
-
const result = await respectifyClient.initTopicFromUrl(postUrl, `Post: ${postSlug}`);
|
|
67
71
|
articleIdCache.set(postSlug, result.article_id);
|
|
68
|
-
logger.info('Initialized Respectify topic', { postSlug });
|
|
72
|
+
logger.info('Initialized Respectify topic', { postSlug, source: getPostContent ? 'text' : 'url' });
|
|
69
73
|
|
|
70
74
|
return result.article_id;
|
|
71
75
|
}
|
|
@@ -82,6 +86,10 @@ export async function verifyRespectifyCredentials(): Promise<boolean> {
|
|
|
82
86
|
}
|
|
83
87
|
}
|
|
84
88
|
|
|
89
|
+
/** Shown for suspected spam when an API sends no suggestion. */
|
|
90
|
+
const DEFAULT_SUSPECTED_SPAM_SUGGESTION =
|
|
91
|
+
'This looks like spam. Please revise it and say what you think about the discussion.';
|
|
92
|
+
|
|
85
93
|
function buildSuggestion(result: MegaCallResult, showFeedback: boolean): string | undefined {
|
|
86
94
|
if (!showFeedback || !result.comment_score) return undefined;
|
|
87
95
|
|
|
@@ -112,6 +120,37 @@ function buildSuggestion(result: MegaCallResult, showFeedback: boolean): string
|
|
|
112
120
|
return suggestions.length > 0 ? suggestions.join(' ') : undefined;
|
|
113
121
|
}
|
|
114
122
|
|
|
123
|
+
/**
|
|
124
|
+
* Approve, warn or block on the comment's content.
|
|
125
|
+
*
|
|
126
|
+
* With a comment score, `exceeds_tolerance` decides whether there is a problem at all:
|
|
127
|
+
* - false: approved, whatever the toxicity (toxicity_score is not adjusted for the site's
|
|
128
|
+
* tolerances, so a comment the site accepts is not held back by it)
|
|
129
|
+
* - true: blocked when respectfulness < thresholds.block and blockDisrespectful is on;
|
|
130
|
+
* otherwise a warning, approved only when allowOverride is on
|
|
131
|
+
*
|
|
132
|
+
* Without exceeds_tolerance the respectfulness bands decide as before: >= autoApprove
|
|
133
|
+
* approves, < block blocks, anything between warns. With no comment score at all the score
|
|
134
|
+
* is autoApprove, so the comment is approved; a comment score lacking exceeds_tolerance
|
|
135
|
+
* (an API older than moderation tolerances) falls back to the bands on 1 - toxicity_score.
|
|
136
|
+
*/
|
|
137
|
+
function decideOnContent(
|
|
138
|
+
config: RespectifyConfig,
|
|
139
|
+
respectfulnessScore: number,
|
|
140
|
+
exceedsTolerance: boolean | undefined,
|
|
141
|
+
): Pick<RespectifyAnalysisResult, 'approved' | 'feedback'> {
|
|
142
|
+
const isWithinTolerance =
|
|
143
|
+
exceedsTolerance === undefined ? respectfulnessScore >= config.thresholds.autoApprove : !exceedsTolerance;
|
|
144
|
+
|
|
145
|
+
if (isWithinTolerance) {
|
|
146
|
+
return { approved: true, feedback: config.feedback.approved };
|
|
147
|
+
}
|
|
148
|
+
if (respectfulnessScore < config.thresholds.block && config.moderation.blockDisrespectful) {
|
|
149
|
+
return { approved: false, feedback: config.feedback.blocked };
|
|
150
|
+
}
|
|
151
|
+
return { approved: config.moderation.allowOverride, feedback: config.feedback.warning };
|
|
152
|
+
}
|
|
153
|
+
|
|
115
154
|
export async function analyzeComment(
|
|
116
155
|
text: string,
|
|
117
156
|
postSlug?: string,
|
|
@@ -165,6 +204,12 @@ export async function analyzeComment(
|
|
|
165
204
|
megacallOptions.replyToComment = options.replyToComment;
|
|
166
205
|
}
|
|
167
206
|
|
|
207
|
+
// Tolerances only shape the comment score, which needs topic context
|
|
208
|
+
const tolerances = resolveTolerances(config);
|
|
209
|
+
if (tolerances && megacallOptions.includeCommentScore) {
|
|
210
|
+
megacallOptions.tolerances = tolerances;
|
|
211
|
+
}
|
|
212
|
+
|
|
168
213
|
const result = await respectifyClient.megacall(megacallOptions);
|
|
169
214
|
const showFeedback = config.moderation.showFeedbackToUser !== false;
|
|
170
215
|
|
|
@@ -174,10 +219,22 @@ export async function analyzeComment(
|
|
|
174
219
|
approved: false,
|
|
175
220
|
feedback: 'This comment appears to be spam.',
|
|
176
221
|
isSpam: true,
|
|
222
|
+
suspectedSpam: false,
|
|
177
223
|
spamConfidence: result.spam_check.confidence,
|
|
178
224
|
};
|
|
179
225
|
}
|
|
180
226
|
|
|
227
|
+
// Suspected spam is not spam: the other checks still run, but the comment is sent back
|
|
228
|
+
// with the server's suggestion. An older API omits suspected_spam, meaning not suspected.
|
|
229
|
+
const spamFields: Pick<RespectifyAnalysisResult, 'isSpam' | 'suspectedSpam' | 'spamSuggestion'> = {};
|
|
230
|
+
if (result.spam_check) {
|
|
231
|
+
spamFields.isSpam = false;
|
|
232
|
+
spamFields.suspectedSpam = result.spam_check.suspected_spam === true;
|
|
233
|
+
if (spamFields.suspectedSpam) {
|
|
234
|
+
spamFields.spamSuggestion = result.spam_check.suggestion || DEFAULT_SUSPECTED_SPAM_SUGGESTION;
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
|
|
181
238
|
const blockOffTopic = config.moderation.blockOffTopic !== false;
|
|
182
239
|
if (blockOffTopic && result.relevance_check) {
|
|
183
240
|
const { on_topic, banned_topics } = result.relevance_check;
|
|
@@ -188,6 +245,7 @@ export async function analyzeComment(
|
|
|
188
245
|
approved: false,
|
|
189
246
|
feedback: config.feedback.offTopic ?? 'This comment appears to be off-topic.',
|
|
190
247
|
suggestion: showFeedback ? on_topic.reasoning || banned_topics.reasoning : undefined,
|
|
248
|
+
...spamFields,
|
|
191
249
|
};
|
|
192
250
|
}
|
|
193
251
|
}
|
|
@@ -199,35 +257,32 @@ export async function analyzeComment(
|
|
|
199
257
|
approved: false,
|
|
200
258
|
feedback: config.feedback.dogwhistle ?? 'This comment was blocked due to policy violations.',
|
|
201
259
|
suggestion: showFeedback ? result.dogwhistle_check.detection.reasoning : undefined,
|
|
260
|
+
...spamFields,
|
|
202
261
|
};
|
|
203
262
|
}
|
|
204
263
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
let approved = false;
|
|
213
|
-
let feedback = '';
|
|
264
|
+
// Respectfulness is 1 - toxicity_score. Without a comment score there is nothing to
|
|
265
|
+
// judge content by, so the comment is treated as at the auto-approve threshold.
|
|
266
|
+
const respectfulnessScore = result.comment_score
|
|
267
|
+
? 1 - (result.comment_score.toxicity_score ?? 0)
|
|
268
|
+
: config.thresholds.autoApprove;
|
|
269
|
+
const exceedsTolerance = result.comment_score?.exceeds_tolerance;
|
|
214
270
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
feedback = config.feedback.blocked;
|
|
221
|
-
} else {
|
|
222
|
-
approved = config.moderation.allowOverride;
|
|
223
|
-
feedback = config.feedback.warning;
|
|
224
|
-
}
|
|
271
|
+
const contentDecision = decideOnContent(config, respectfulnessScore, exceedsTolerance);
|
|
272
|
+
// Suspected spam always goes back to the commenter, whatever the content decision
|
|
273
|
+
const { approved, feedback } = spamFields.spamSuggestion
|
|
274
|
+
? { approved: false, feedback: spamFields.spamSuggestion }
|
|
275
|
+
: contentDecision;
|
|
225
276
|
|
|
226
277
|
const analysisResult: RespectifyAnalysisResult = {
|
|
227
278
|
score: respectfulnessScore,
|
|
228
279
|
approved,
|
|
229
280
|
feedback,
|
|
281
|
+
...spamFields,
|
|
230
282
|
};
|
|
283
|
+
if (exceedsTolerance !== undefined) analysisResult.exceedsTolerance = exceedsTolerance;
|
|
284
|
+
if (result.comment_score?.health_score !== undefined) analysisResult.healthScore = result.comment_score.health_score;
|
|
285
|
+
if (result.comment_score?.health_items !== undefined) analysisResult.healthItems = result.comment_score.health_items;
|
|
231
286
|
|
|
232
287
|
const suggestion = buildSuggestion(result, showFeedback);
|
|
233
288
|
if (suggestion) analysisResult.suggestion = suggestion;
|
package/src/runtime-config.ts
CHANGED
|
@@ -3,16 +3,18 @@ import type { RespectifyIntegrationOptions, RespectifyClientConfig, RespectifyMe
|
|
|
3
3
|
export type ResolvedIntegrationOptions = Required<
|
|
4
4
|
Pick<RespectifyIntegrationOptions, 'configPath' | 'commentsApiPath' | 'showBranding'>
|
|
5
5
|
> &
|
|
6
|
-
Pick<RespectifyIntegrationOptions, 'getPostUrl' | 'rateLimit' | 'client' | 'megacall'>;
|
|
6
|
+
Pick<RespectifyIntegrationOptions, 'getPostUrl' | 'getPostContent' | 'rateLimit' | 'client' | 'megacall' | 'tolerances'>;
|
|
7
7
|
|
|
8
8
|
const defaults: ResolvedIntegrationOptions = {
|
|
9
9
|
configPath: './respectify.config.json',
|
|
10
10
|
commentsApiPath: '/api/respectify/comments',
|
|
11
11
|
showBranding: true,
|
|
12
12
|
getPostUrl: (slug, site) => `${site.replace(/\/$/, '')}/posts/${slug}/`,
|
|
13
|
+
getPostContent: undefined,
|
|
13
14
|
rateLimit: { windowMs: 5 * 60 * 1000, maxRequests: 10 },
|
|
14
15
|
client: undefined,
|
|
15
16
|
megacall: undefined,
|
|
17
|
+
tolerances: undefined,
|
|
16
18
|
};
|
|
17
19
|
|
|
18
20
|
let options: ResolvedIntegrationOptions = { ...defaults };
|
|
@@ -22,9 +24,11 @@ export function setIntegrationOptions(userOptions: RespectifyIntegrationOptions
|
|
|
22
24
|
...defaults,
|
|
23
25
|
...userOptions,
|
|
24
26
|
getPostUrl: userOptions.getPostUrl ?? defaults.getPostUrl,
|
|
27
|
+
getPostContent: userOptions.getPostContent,
|
|
25
28
|
rateLimit: userOptions.rateLimit ?? defaults.rateLimit,
|
|
26
29
|
client: userOptions.client,
|
|
27
30
|
megacall: userOptions.megacall,
|
|
31
|
+
tolerances: userOptions.tolerances,
|
|
28
32
|
};
|
|
29
33
|
}
|
|
30
34
|
|
package/src/types.ts
CHANGED
|
@@ -1,4 +1,9 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type {
|
|
2
|
+
HealthItemScores,
|
|
3
|
+
MegacallOptions,
|
|
4
|
+
ModerationTolerances,
|
|
5
|
+
RespectifyClientOptions,
|
|
6
|
+
} from '@respectify/client';
|
|
2
7
|
|
|
3
8
|
/**
|
|
4
9
|
* Options forwarded to `RespectifyClient`.
|
|
@@ -8,9 +13,10 @@ export type RespectifyClientConfig = Partial<RespectifyClientOptions>;
|
|
|
8
13
|
|
|
9
14
|
/**
|
|
10
15
|
* Options forwarded to every `megacall`.
|
|
11
|
-
* `comment` and `articleId` are set automatically by the integration
|
|
16
|
+
* `comment` and `articleId` are set automatically by the integration, and
|
|
17
|
+
* `tolerances` comes from the top-level `tolerances` option.
|
|
12
18
|
*/
|
|
13
|
-
export type RespectifyMegacallConfig = Omit<MegacallOptions, 'comment' | 'articleId'>;
|
|
19
|
+
export type RespectifyMegacallConfig = Omit<MegacallOptions, 'comment' | 'articleId' | 'tolerances'>;
|
|
14
20
|
|
|
15
21
|
export interface RespectifyIntegrationOptions {
|
|
16
22
|
/** Path to respectify.config.json (default: ./respectify.config.json) */
|
|
@@ -19,6 +25,14 @@ export interface RespectifyIntegrationOptions {
|
|
|
19
25
|
/** Build the canonical URL for a post — used to initialize Respectify topics */
|
|
20
26
|
getPostUrl?: (slug: string, site: string) => string;
|
|
21
27
|
|
|
28
|
+
/**
|
|
29
|
+
* Provide a post's raw text content directly instead of having Respectify fetch
|
|
30
|
+
* `getPostUrl`. Useful when the URL isn't publicly fetchable (staged/preview content,
|
|
31
|
+
* auth-gated pages, or timing issues right after deploy). Takes priority over
|
|
32
|
+
* `getPostUrl` for topic initialization when provided.
|
|
33
|
+
*/
|
|
34
|
+
getPostContent?: (slug: string) => string | Promise<string>;
|
|
35
|
+
|
|
22
36
|
/** API route path for fetching comments (default: /api/respectify/comments) */
|
|
23
37
|
commentsApiPath?: string;
|
|
24
38
|
|
|
@@ -43,6 +57,14 @@ export interface RespectifyIntegrationOptions {
|
|
|
43
57
|
* `bannedTopics`, `sensitiveTopics`, `dogwhistleExamples`, `replyToComment`).
|
|
44
58
|
*/
|
|
45
59
|
megacall?: RespectifyMegacallConfig;
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Comment-health tolerances sent with every megacall, merged per item over the
|
|
63
|
+
* `tolerances` in respectify.config.json (these win). Items not named are "standard".
|
|
64
|
+
* Floored categories (threat, identity_attack, sexual_content, harassment) can never
|
|
65
|
+
* be "permissive", "relaxed" or "off".
|
|
66
|
+
*/
|
|
67
|
+
tolerances?: ModerationTolerances;
|
|
46
68
|
}
|
|
47
69
|
|
|
48
70
|
export interface AnalyzeCommentOptions {
|
|
@@ -55,6 +77,21 @@ export interface RespectifyAnalysisResult {
|
|
|
55
77
|
approved: boolean;
|
|
56
78
|
feedback: string;
|
|
57
79
|
suggestion?: string;
|
|
80
|
+
/** True when the comment is spam: it is rejected */
|
|
58
81
|
isSpam?: boolean;
|
|
59
82
|
spamConfidence?: number;
|
|
83
|
+
/**
|
|
84
|
+
* True when the comment looks like spam but is not certain. It is not approved (never,
|
|
85
|
+
* even with `allowOverride`), but it is not rejected as spam either: `feedback` carries
|
|
86
|
+
* the server's suggestion so the commenter can revise it. Set when a spam check ran.
|
|
87
|
+
*/
|
|
88
|
+
suspectedSpam?: boolean;
|
|
89
|
+
/** The server's suggestion for a suspected-spam comment, such as to remove a link */
|
|
90
|
+
spamSuggestion?: string;
|
|
91
|
+
/** True when the comment score found a problem the site's tolerances do not accept */
|
|
92
|
+
exceedsTolerance?: boolean;
|
|
93
|
+
/** Comment health, 1.0-5.0, when the API returned it */
|
|
94
|
+
healthScore?: number;
|
|
95
|
+
/** Per-item comment-health results (score, minimum, is_acceptable), when the API returned them */
|
|
96
|
+
healthItems?: HealthItemScores;
|
|
60
97
|
}
|