@respectify/astro 1.0.2 → 1.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.
@@ -4,13 +4,17 @@ import { RESPECTIFY_API_KEY, RESPECTIFY_EMAIL } from 'astro:env/server';
4
4
  import {
5
5
  RespectifyClient,
6
6
  AuthenticationError,
7
+ FreeAllowanceExhaustedError,
7
8
  PaymentRequiredError,
9
+ RateLimitedError,
8
10
  RespectifyError,
11
+ RevisionLimitReachedError,
9
12
  type MegacallOptions,
10
13
  type MegaCallResult,
11
14
  } from '@respectify/client';
12
15
  import { getRespectifyRuntime } from '../runtime';
13
16
  import { logger } from './logger';
17
+ import { HELD_FOR_REVIEW_MESSAGE } from './messages';
14
18
  import type { AnalyzeCommentOptions, RespectifyAnalysisResult } from '../types';
15
19
 
16
20
  let client: RespectifyClient | null = null;
@@ -210,8 +214,16 @@ export async function analyzeComment(
210
214
  megacallOptions.tolerances = tolerances;
211
215
  }
212
216
 
213
- const result = await respectifyClient.megacall(megacallOptions);
217
+ // A revised resubmission carries the token its previous analysis returned
218
+ if (options.revisionToken !== undefined) {
219
+ megacallOptions.revisionToken = options.revisionToken;
220
+ }
221
+
222
+ const { result, revisionToken } = await respectifyClient.megacallWithMeta(megacallOptions);
214
223
  const showFeedback = config.moderation.showFeedbackToUser !== false;
224
+ // Free-plan accounts get a token to send back with a revision; paid accounts get none
225
+ const tokenField: Pick<RespectifyAnalysisResult, 'revisionToken'> =
226
+ revisionToken === undefined ? {} : { revisionToken };
215
227
 
216
228
  if (result.spam_check?.is_spam) {
217
229
  return {
@@ -221,6 +233,7 @@ export async function analyzeComment(
221
233
  isSpam: true,
222
234
  suspectedSpam: false,
223
235
  spamConfidence: result.spam_check.confidence,
236
+ ...tokenField,
224
237
  };
225
238
  }
226
239
 
@@ -246,6 +259,7 @@ export async function analyzeComment(
246
259
  feedback: config.feedback.offTopic ?? 'This comment appears to be off-topic.',
247
260
  suggestion: showFeedback ? on_topic.reasoning || banned_topics.reasoning : undefined,
248
261
  ...spamFields,
262
+ ...tokenField,
249
263
  };
250
264
  }
251
265
  }
@@ -258,6 +272,7 @@ export async function analyzeComment(
258
272
  feedback: config.feedback.dogwhistle ?? 'This comment was blocked due to policy violations.',
259
273
  suggestion: showFeedback ? result.dogwhistle_check.detection.reasoning : undefined,
260
274
  ...spamFields,
275
+ ...tokenField,
261
276
  };
262
277
  }
263
278
 
@@ -279,6 +294,7 @@ export async function analyzeComment(
279
294
  approved,
280
295
  feedback,
281
296
  ...spamFields,
297
+ ...tokenField,
282
298
  };
283
299
  if (exceedsTolerance !== undefined) analysisResult.exceedsTolerance = exceedsTolerance;
284
300
  if (result.comment_score?.health_score !== undefined) analysisResult.healthScore = result.comment_score.health_score;
@@ -289,10 +305,31 @@ export async function analyzeComment(
289
305
 
290
306
  return analysisResult;
291
307
  } catch (error) {
308
+ if (error instanceof FreeAllowanceExhaustedError) {
309
+ return publishUnmoderated(config, error, postSlug);
310
+ }
311
+
312
+ if (error instanceof RevisionLimitReachedError) {
313
+ // The comment cannot be revised again through the API: a person decides instead
314
+ logger.info('Respectify revision limit reached; holding the comment for review', { postSlug });
315
+ return {
316
+ score: 0,
317
+ approved: false,
318
+ heldForReview: true,
319
+ feedback: HELD_FOR_REVIEW_MESSAGE,
320
+ };
321
+ }
322
+
292
323
  if (error instanceof AuthenticationError) {
293
324
  logger.error('Respectify authentication failed', { error });
294
325
  } else if (error instanceof PaymentRequiredError) {
295
326
  logger.error('Respectify subscription required', { error });
327
+ } else if (error instanceof RateLimitedError) {
328
+ logger.error('Respectify rate limit reached', {
329
+ errorCode: error.errorCode,
330
+ retryAfterSeconds: error.retryAfterSeconds,
331
+ message: error.message,
332
+ });
296
333
  } else if (error instanceof RespectifyError) {
297
334
  logger.error('Respectify API error', { statusCode: error.statusCode, message: error.message });
298
335
  } else {
@@ -306,3 +343,41 @@ export async function analyzeComment(
306
343
  };
307
344
  }
308
345
  }
346
+
347
+ /**
348
+ * The account's free plan is used up, so Respectify no longer assesses comments. The comment
349
+ * is approved as it is (the commenter sees the ordinary approval), and the site owner is told
350
+ * through the log and the runtime's `onModerationStopped`.
351
+ */
352
+ async function publishUnmoderated(
353
+ config: RespectifyConfig,
354
+ error: FreeAllowanceExhaustedError,
355
+ postSlug: string | undefined,
356
+ ): Promise<RespectifyAnalysisResult> {
357
+ logger.error('Respectify moderation stopped: the free plan is used up. Comments are being published unmoderated.', {
358
+ upgradeUrl: error.upgradeUrl,
359
+ message: error.message,
360
+ postSlug,
361
+ });
362
+
363
+ const { onModerationStopped } = getRespectifyRuntime();
364
+ if (onModerationStopped) {
365
+ try {
366
+ await onModerationStopped({
367
+ reason: 'free_allowance_exhausted',
368
+ upgradeUrl: error.upgradeUrl,
369
+ message: error.message,
370
+ postSlug,
371
+ });
372
+ } catch (callbackError) {
373
+ logger.error('onModerationStopped failed', { error: callbackError });
374
+ }
375
+ }
376
+
377
+ return {
378
+ score: config.thresholds.autoApprove,
379
+ approved: true,
380
+ feedback: config.feedback.approved,
381
+ moderationSkipped: { reason: 'free_allowance_exhausted', upgradeUrl: error.upgradeUrl },
382
+ };
383
+ }
package/src/options.ts CHANGED
@@ -9,6 +9,9 @@ import type {
9
9
  } from './types';
10
10
 
11
11
  /** The options the server bundle sees when `respectify()` is given only `runtime`. */
12
+ /** Where the runtime module is looked for when `respectify()` is not told. `respectify-astro init` writes it there. */
13
+ export const DEFAULT_RUNTIME_MODULE = './src/respectify.runtime.ts';
14
+
12
15
  export const DEFAULT_INTEGRATION_OPTIONS: ResolvedIntegrationOptions = {
13
16
  configPath: './respectify.config.json',
14
17
  commentsApiPath: '/api/respectify/comments',
@@ -53,7 +56,10 @@ const tolerancesSchema = z.custom<ModerationTolerances>().superRefine((tolerance
53
56
  });
54
57
 
55
58
  const integrationOptionsSchema = z.strictObject({
56
- runtime: z.string().min(1, 'runtime must name the module that calls defineRespectifyRuntime()'),
59
+ runtime: z
60
+ .string()
61
+ .min(1, 'runtime must name the module that calls defineRespectifyRuntime()')
62
+ .default(DEFAULT_RUNTIME_MODULE),
57
63
  configPath: z.string().min(1).default(DEFAULT_INTEGRATION_OPTIONS.configPath),
58
64
  commentsApiPath: z
59
65
  .string()
package/src/runtime.ts CHANGED
@@ -24,5 +24,7 @@ export function getRespectifyRuntime(): ResolvedRespectifyRuntime {
24
24
  store: runtime.store,
25
25
  getPostUrl: runtime.getPostUrl ?? defaultGetPostUrl,
26
26
  getPostContent: runtime.getPostContent,
27
+ onModerationStopped: runtime.onModerationStopped,
28
+ onHeldForReview: runtime.onHeldForReview,
27
29
  };
28
30
  }
package/src/types.ts CHANGED
@@ -4,7 +4,7 @@ import type {
4
4
  ModerationTolerances,
5
5
  RespectifyClientOptions,
6
6
  } from '@respectify/client';
7
- import type { ICommentStore } from './store/types';
7
+ import type { CommentRecord, ICommentStore } from './store/types';
8
8
 
9
9
  /**
10
10
  * Options forwarded to `RespectifyClient`.
@@ -35,8 +35,9 @@ export interface RespectifyIntegrationOptions {
35
35
  /**
36
36
  * The runtime module: a file whose default export is `defineRespectifyRuntime({ store, ... })`.
37
37
  * A relative path is resolved against the project root; a package specifier is left to Vite.
38
+ * Default: `./src/respectify.runtime.ts`, the file `respectify-astro init` writes.
38
39
  */
39
- runtime: string;
40
+ runtime?: string;
40
41
 
41
42
  /** Path to respectify.config.json (default: ./respectify.config.json) */
42
43
  configPath?: string;
@@ -106,11 +107,63 @@ export interface RespectifyRuntime {
106
107
  * `getPostUrl` for topic initialization when provided.
107
108
  */
108
109
  getPostContent?: (slug: string) => string | Promise<string>;
110
+
111
+ /**
112
+ * Called when Respectify stops moderating because the account's free plan is used up.
113
+ * From then on comments are published unmoderated, so tell yourself: email, Slack, a
114
+ * dashboard flag. Called once per affected comment. Commenters are never told. The event
115
+ * is also logged at error level whether or not this is set.
116
+ */
117
+ onModerationStopped?: (event: ModerationStoppedEvent) => void | Promise<void>;
118
+
119
+ /**
120
+ * Called when a comment is stored for you to review instead of being published or
121
+ * rejected: on the free plan, a comment that has used all five of its attempts. The
122
+ * comment is in your store with `approved: false`; set `approved` to true to publish it,
123
+ * or delete it.
124
+ */
125
+ onHeldForReview?: (event: HeldForReviewEvent) => void | Promise<void>;
126
+ }
127
+
128
+ /** Why moderation stopped. Only the free plan can run out today. */
129
+ export type ModerationStoppedReason = 'free_allowance_exhausted';
130
+
131
+ /** What `onModerationStopped` receives. */
132
+ export interface ModerationStoppedEvent {
133
+ reason: ModerationStoppedReason;
134
+ /** Where to add credit so moderation resumes */
135
+ upgradeUrl: string;
136
+ /** The API's own message, which already names the upgrade URL */
137
+ message: string;
138
+ /** The post the unmoderated comment was published on */
139
+ postSlug: string | undefined;
140
+ }
141
+
142
+ /** Why a comment was held rather than published or rejected. */
143
+ export type HeldForReviewReason = 'revision_limit_reached';
144
+
145
+ /** What `onHeldForReview` receives. */
146
+ export interface HeldForReviewEvent {
147
+ reason: HeldForReviewReason;
148
+ /** The stored comment, with `approved: false` */
149
+ comment: CommentRecord;
109
150
  }
110
151
 
111
152
  export interface AnalyzeCommentOptions {
112
153
  /** Parent comment text when submitting a reply */
113
154
  replyToComment?: string;
155
+ /**
156
+ * The revision token the previous analysis of this same comment returned, when the
157
+ * commenter is resubmitting a revised version (see `RespectifyAnalysisResult.revisionToken`).
158
+ */
159
+ revisionToken?: string;
160
+ }
161
+
162
+ /** Moderation did not run on this comment; it was published as it was. */
163
+ export interface ModerationSkipped {
164
+ reason: ModerationStoppedReason;
165
+ /** Where to add credit so moderation resumes */
166
+ upgradeUrl: string;
114
167
  }
115
168
 
116
169
  export interface RespectifyAnalysisResult {
@@ -118,6 +171,23 @@ export interface RespectifyAnalysisResult {
118
171
  approved: boolean;
119
172
  feedback: string;
120
173
  suggestion?: string;
174
+ /**
175
+ * Set when the comment went through unmoderated because the account's free plan is used
176
+ * up. `approved` is true: publish it as it is, and tell the site owner, never the commenter.
177
+ */
178
+ moderationSkipped?: ModerationSkipped;
179
+ /**
180
+ * True when the comment should be stored unpublished for the site owner to review, rather
181
+ * than rejected: on the free plan, when it has used all five of its attempts. `approved`
182
+ * is false.
183
+ */
184
+ heldForReview?: boolean;
185
+ /**
186
+ * On the free plan, the token to send back (as `AnalyzeCommentOptions.revisionToken`) if the
187
+ * commenter revises this comment, so the revision is not counted as a new comment. Absent
188
+ * for paid accounts.
189
+ */
190
+ revisionToken?: string;
121
191
  /** True when the comment is spam: it is rejected */
122
192
  isSpam?: boolean;
123
193
  spamConfidence?: number;