adula 2.1.0 → 2.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.
Files changed (214) hide show
  1. package/README.md +149 -18
  2. package/build/agent/AGENTS.template.md +4 -4
  3. package/build/agent/capabilities.md +22 -11
  4. package/build/agent/skills/adula-frontend-design/SKILL.md +1 -1
  5. package/build/agent/skills/idea-review/SKILL.md +2 -2
  6. package/build/commands/adula_outbox.d.ts +10 -0
  7. package/build/commands/adula_outbox.js +11 -0
  8. package/build/commands/adula_restore_reconcile.d.ts +10 -0
  9. package/build/commands/adula_restore_reconcile.js +34 -0
  10. package/build/commands/adula_runtime_health.d.ts +10 -0
  11. package/build/commands/adula_runtime_health.js +27 -0
  12. package/build/commands/adula_uploads_prune.d.ts +10 -0
  13. package/build/commands/adula_uploads_prune.js +16 -0
  14. package/build/commands/app.d.ts +10 -0
  15. package/build/commands/app.js +64 -0
  16. package/build/commands/backup_create.d.ts +11 -0
  17. package/build/commands/backup_create.js +99 -0
  18. package/build/commands/backup_restore_files.d.ts +11 -0
  19. package/build/commands/backup_restore_files.js +44 -0
  20. package/build/commands/backup_restore_test.d.ts +12 -0
  21. package/build/commands/backup_restore_test.js +185 -0
  22. package/build/commands/backup_services.d.ts +31 -0
  23. package/build/commands/backup_services.js +6 -0
  24. package/build/commands/backup_verify.d.ts +9 -0
  25. package/build/commands/backup_verify.js +59 -0
  26. package/build/commands/backup_verify_snapshot.d.ts +10 -0
  27. package/build/commands/backup_verify_snapshot.js +37 -0
  28. package/build/commands/client.d.ts +16 -0
  29. package/build/commands/client.js +71 -0
  30. package/build/commands/doctor.js +4 -1
  31. package/build/commands/install.d.ts +8 -0
  32. package/build/commands/install.js +63 -45
  33. package/build/commands/main.d.ts +3 -2
  34. package/build/commands/main.js +26 -0
  35. package/build/commands/module_add.js +4 -20
  36. package/build/commands/resource.d.ts +2 -0
  37. package/build/commands/resource.js +12 -3
  38. package/build/commands/resource_migration.d.ts +15 -0
  39. package/build/commands/resource_migration.js +72 -0
  40. package/build/commands/resource_snapshot.d.ts +2 -0
  41. package/build/commands/resource_snapshot.js +3 -0
  42. package/build/commands/sla_evaluate.d.ts +14 -0
  43. package/build/commands/sla_evaluate.js +16 -0
  44. package/build/commands/ui.js +4 -2
  45. package/build/commands/ui_css.d.ts +9 -0
  46. package/build/commands/ui_css.js +19 -0
  47. package/build/commands/upgrade.d.ts +1 -1
  48. package/build/commands/upgrade.js +1 -1
  49. package/build/configure.js +1 -1
  50. package/build/database/migrations/1770000000020_two_factor.d.ts +5 -0
  51. package/build/database/migrations/1770000000020_two_factor.js +10 -0
  52. package/build/database/migrations/1770000000041_import_modes.d.ts +5 -0
  53. package/build/database/migrations/1770000000041_import_modes.js +10 -0
  54. package/build/database/migrations/1770000000042_sync_jobs.d.ts +5 -0
  55. package/build/database/migrations/1770000000042_sync_jobs.js +10 -0
  56. package/build/database/migrations/1770000000043_notification_channels.d.ts +5 -0
  57. package/build/database/migrations/1770000000043_notification_channels.js +10 -0
  58. package/build/database/migrations/1770000000044_channel_confirmations.d.ts +5 -0
  59. package/build/database/migrations/1770000000044_channel_confirmations.js +10 -0
  60. package/build/database/migrations/1770000000045_import_leases.d.ts +5 -0
  61. package/build/database/migrations/1770000000045_import_leases.js +10 -0
  62. package/build/database/migrations/1770000000046_workflow_delegation_sla.d.ts +5 -0
  63. package/build/database/migrations/1770000000046_workflow_delegation_sla.js +10 -0
  64. package/build/database/migrations/1770000000049_print_templates.d.ts +5 -0
  65. package/build/database/migrations/1770000000049_print_templates.js +10 -0
  66. package/build/index.d.ts +56 -10
  67. package/build/index.js +34 -6
  68. package/build/providers/adula_provider.d.ts +2 -0
  69. package/build/providers/adula_provider.js +7 -0
  70. package/build/src/admin/contracts.js +1 -1
  71. package/build/src/admin/controller.d.ts +14 -1
  72. package/build/src/admin/controller.js +77 -13
  73. package/build/src/admin/errors.d.ts +32 -0
  74. package/build/src/admin/errors.js +63 -1
  75. package/build/src/admin/presentation.d.ts +21 -2
  76. package/build/src/admin/resource/editor.d.ts +59 -0
  77. package/build/src/admin/resource/editor.js +323 -0
  78. package/build/src/admin/resource/export.d.ts +37 -0
  79. package/build/src/admin/resource/export.js +181 -0
  80. package/build/src/admin/resource/lifecycle.d.ts +21 -0
  81. package/build/src/admin/resource/lifecycle.js +91 -0
  82. package/build/src/admin/resource/query.d.ts +100 -0
  83. package/build/src/admin/resource/query.js +508 -0
  84. package/build/src/admin/resource/read.d.ts +106 -0
  85. package/build/src/admin/resource/read.js +327 -0
  86. package/build/src/admin/resource/shared.d.ts +77 -0
  87. package/build/src/admin/resource/shared.js +222 -0
  88. package/build/src/admin/resource/trash.d.ts +10 -0
  89. package/build/src/admin/resource/trash.js +56 -0
  90. package/build/src/admin/resource/write.d.ts +57 -0
  91. package/build/src/admin/resource/write.js +574 -0
  92. package/build/src/admin/resource_service.d.ts +66 -193
  93. package/build/src/admin/resource_service.js +69 -1345
  94. package/build/src/attachments/attachment_service.d.ts +46 -2
  95. package/build/src/attachments/attachment_service.js +96 -4
  96. package/build/src/auth/conditions.d.ts +5 -0
  97. package/build/src/auth/conditions.js +26 -3
  98. package/build/src/auth/sql.js +17 -5
  99. package/build/src/auth/two_factor.d.ts +96 -0
  100. package/build/src/auth/two_factor.js +259 -0
  101. package/build/src/collaboration/assignments.d.ts +36 -1
  102. package/build/src/collaboration/assignments.js +132 -66
  103. package/build/src/collaboration/record_collaboration.d.ts +2 -3
  104. package/build/src/collaboration/record_collaboration.js +19 -16
  105. package/build/src/collaboration/shared.d.ts +16 -0
  106. package/build/src/collaboration/shared.js +21 -0
  107. package/build/src/commands/app_scaffold.d.ts +72 -0
  108. package/build/src/commands/app_scaffold.js +285 -0
  109. package/build/src/commands/capabilities.js +34 -8
  110. package/build/src/commands/doctor.d.ts +14 -2
  111. package/build/src/commands/doctor.js +50 -5
  112. package/build/src/commands/gap_report.d.ts +1 -1
  113. package/build/src/commands/gap_report.js +2 -2
  114. package/build/src/commands/generator.d.ts +37 -1
  115. package/build/src/commands/generator.js +61 -18
  116. package/build/src/commands/snapshot.d.ts +10 -13
  117. package/build/src/commands/snapshot.js +31 -14
  118. package/build/src/commands/source_markers.d.ts +10 -0
  119. package/build/src/commands/source_markers.js +29 -0
  120. package/build/src/core/activity.d.ts +2 -0
  121. package/build/src/core/activity.js +7 -1
  122. package/build/src/core/administrators.d.ts +38 -0
  123. package/build/src/core/administrators.js +129 -0
  124. package/build/src/core/html_sanitizer.d.ts +20 -0
  125. package/build/src/core/html_sanitizer.js +261 -0
  126. package/build/src/core/like.d.ts +5 -0
  127. package/build/src/core/like.js +5 -0
  128. package/build/src/core/lookups.d.ts +80 -0
  129. package/build/src/core/lookups.js +319 -0
  130. package/build/src/core/message_templates.d.ts +7 -2
  131. package/build/src/core/message_templates.js +72 -11
  132. package/build/src/core/module_seed.js +2 -1
  133. package/build/src/core/notification_channels.d.ts +235 -0
  134. package/build/src/core/notification_channels.js +660 -0
  135. package/build/src/core/roles.js +2 -2
  136. package/build/src/core/saved_views.d.ts +8 -1
  137. package/build/src/core/saved_views.js +36 -2
  138. package/build/src/core/sequences.d.ts +32 -0
  139. package/build/src/core/sequences.js +97 -0
  140. package/build/src/core/settings.d.ts +5 -0
  141. package/build/src/core/settings.js +19 -2
  142. package/build/src/core/template_language.d.ts +61 -0
  143. package/build/src/core/template_language.js +141 -0
  144. package/build/src/core/ui_preferences.d.ts +4 -0
  145. package/build/src/core/ui_preferences.js +4 -1
  146. package/build/src/core/user_invitations.d.ts +5 -1
  147. package/build/src/core/user_invitations.js +7 -1
  148. package/build/src/core/users.js +1 -1
  149. package/build/src/database/calendar_days.d.ts +19 -0
  150. package/build/src/database/calendar_days.js +36 -0
  151. package/build/src/database/schema.d.ts +155 -2
  152. package/build/src/database/schema.js +531 -59
  153. package/build/src/database/schema_diff.d.ts +56 -0
  154. package/build/src/database/schema_diff.js +157 -0
  155. package/build/src/events/record_mutation.d.ts +2 -1
  156. package/build/src/events/record_mutation.js +1 -0
  157. package/build/src/integrations/api_client.d.ts +37 -0
  158. package/build/src/integrations/api_client.js +552 -0
  159. package/build/src/integrations/import_adapters.d.ts +37 -0
  160. package/build/src/integrations/import_adapters.js +35 -0
  161. package/build/src/integrations/imports.d.ts +118 -16
  162. package/build/src/integrations/imports.js +406 -73
  163. package/build/src/integrations/openapi.d.ts +3 -1
  164. package/build/src/integrations/openapi.js +454 -31
  165. package/build/src/integrations/outbound.d.ts +51 -0
  166. package/build/src/integrations/outbound.js +195 -0
  167. package/build/src/integrations/print.d.ts +21 -1
  168. package/build/src/integrations/print.js +63 -21
  169. package/build/src/integrations/print_templates.d.ts +216 -0
  170. package/build/src/integrations/print_templates.js +1015 -0
  171. package/build/src/integrations/sync_jobs.d.ts +139 -0
  172. package/build/src/integrations/sync_jobs.js +416 -0
  173. package/build/src/integrations/webhooks.d.ts +12 -12
  174. package/build/src/integrations/webhooks.js +34 -43
  175. package/build/src/languages/ar.d.ts +11 -0
  176. package/build/src/languages/ar.js +336 -0
  177. package/build/src/languages/ar_ui.d.ts +332 -0
  178. package/build/src/languages/ar_ui.js +333 -0
  179. package/build/src/languages/catalog.d.ts +66 -0
  180. package/build/src/languages/catalog.js +152 -0
  181. package/build/src/languages/en.d.ts +7 -0
  182. package/build/src/languages/en.js +330 -0
  183. package/build/src/languages/en_ui.d.ts +3 -0
  184. package/build/src/languages/en_ui.js +328 -0
  185. package/build/src/languages/validation.d.ts +26 -0
  186. package/build/src/languages/validation.js +60 -0
  187. package/build/src/lists/bulk_actions.d.ts +89 -0
  188. package/build/src/lists/bulk_actions.js +268 -0
  189. package/build/src/lists/dashboards.d.ts +96 -0
  190. package/build/src/lists/dashboards.js +241 -0
  191. package/build/src/mcp/tools.js +1 -1
  192. package/build/src/resource/define_resource.d.ts +18 -1
  193. package/build/src/resource/define_resource.js +205 -18
  194. package/build/src/resource/definition.d.ts +44 -0
  195. package/build/src/resource/definition.js +171 -0
  196. package/build/src/resource/registry.js +15 -4
  197. package/build/src/resource/types.d.ts +304 -16
  198. package/build/src/resource/values.d.ts +56 -1
  199. package/build/src/resource/values.js +237 -5
  200. package/build/src/services/settings.d.ts +2 -0
  201. package/build/src/services/settings.js +5 -1
  202. package/build/src/upgrade/legacy.js +2 -2
  203. package/build/src/workflows/calendar.d.ts +9 -0
  204. package/build/src/workflows/calendar.js +44 -0
  205. package/build/src/workflows/define_workflow.d.ts +48 -3
  206. package/build/src/workflows/define_workflow.js +57 -13
  207. package/build/src/workflows/delegations.d.ts +93 -0
  208. package/build/src/workflows/delegations.js +287 -0
  209. package/build/src/workflows/engine.d.ts +69 -4
  210. package/build/src/workflows/engine.js +441 -83
  211. package/build/src/workflows/sla.d.ts +15 -0
  212. package/build/src/workflows/sla.js +8 -0
  213. package/build/stubs/resource_contract.txt +12 -1
  214. package/package.json +5 -2
@@ -1,5 +1,7 @@
1
+ import { randomUUID } from 'node:crypto';
1
2
  import { AdulaError } from '../admin/errors.js';
2
3
  import { targetColumns } from '../services/settings.js';
4
+ import { PLACEHOLDER } from './template_language.js';
3
5
  /**
4
6
  * Package-owned defaults. Projects edit wording in the message_templates table;
5
7
  * an upgrade can change a default without overwriting a project's edit.
@@ -68,6 +70,34 @@ export const DEFAULT_TEMPLATES = {
68
70
  variables: ['workflow', 'resource', 'id', 'error'],
69
71
  mail: true,
70
72
  },
73
+ 'workflow.delegated': {
74
+ label: 'تفويض موافقات إليك',
75
+ subject: 'فوّض إليك {{delegator}} موافقاته',
76
+ body: 'من {{from}} إلى {{to}}. تظهر الموافقات المفوّضة في مهامي.',
77
+ variables: ['delegator', 'from', 'to'],
78
+ mail: true,
79
+ },
80
+ 'workflow.sla_due_soon': {
81
+ label: 'اقتراب موعد موافقة',
82
+ subject: 'يقترب موعد موافقة مطلوبة منك',
83
+ body: '{{title}} — {{resource}} #{{id}}، الموعد {{due}}',
84
+ variables: ['title', 'resource', 'id', 'due'],
85
+ mail: true,
86
+ },
87
+ 'workflow.sla_overdue': {
88
+ label: 'تأخر موافقة',
89
+ subject: 'تأخرت موافقة مطلوبة منك',
90
+ body: '{{title}} — {{resource}} #{{id}}، كان الموعد {{due}}',
91
+ variables: ['title', 'resource', 'id', 'due'],
92
+ mail: true,
93
+ },
94
+ 'workflow.sla_escalated': {
95
+ label: 'تصعيد موافقة متأخرة',
96
+ subject: 'صُعّدت إليك موافقة متأخرة',
97
+ body: '{{title}} — {{resource}} #{{id}}، المكلّف {{assignee}}، كان الموعد {{due}}',
98
+ variables: ['title', 'resource', 'id', 'assignee', 'due'],
99
+ mail: true,
100
+ },
71
101
  'webhook.failed': {
72
102
  label: 'تعطل Webhook',
73
103
  subject: 'تعذّر تسليم Webhook: {{name}}',
@@ -83,7 +113,6 @@ export const DEFAULT_TEMPLATES = {
83
113
  mail: false,
84
114
  },
85
115
  };
86
- const PLACEHOLDER = /\{\{\s*([a-zA-Z][a-zA-Z0-9_]*)\s*\}\}/g;
87
116
  const SUBJECT_LIMIT = 200;
88
117
  const BODY_LIMIT = 4000;
89
118
  export function renderTemplate(text, variables) {
@@ -163,20 +192,52 @@ export class MessageTemplates {
163
192
  return definition;
164
193
  }
165
194
  }
195
+ /** The built-in channels: the notification row itself and the mail_state e-mail queue. */
196
+ export const IN_APP_CHANNEL = 'in_app';
197
+ export const MAIL_CHANNEL = 'mail';
166
198
  /**
167
- * Inserts a templated notification in the caller's transaction. Templates with
168
- * mail enabled mark the row for the mail delivery worker (deliverNotificationMail).
199
+ * Inserts a templated notification in the caller's transaction. A template with mail
200
+ * (external delivery) enabled marks the row for the mail worker (deliverNotificationMail)
201
+ * unless the user turned e-mail off, and queues one notification_deliveries row per
202
+ * other channel the user enabled with an address (see core/notification_channels.ts).
169
203
  */
170
204
  export async function notifyWithTemplate(db, userId, key, variables, templates = new MessageTemplates(db), target) {
171
205
  const message = await templates.render(key, variables, db);
172
- await db('notifications').insert({
173
- user_id: userId,
174
- title: message.subject,
175
- body: message.body,
176
- template_key: key,
177
- mail_state: message.mail ? 'pending' : null,
178
- ...targetColumns(target),
179
- });
206
+ const preferences = message.mail
207
+ ? await db('user_notification_channels')
208
+ .where('user_id', userId)
209
+ .select('channel', 'enabled', 'address', 'confirmed_at')
210
+ : [];
211
+ const mailOff = preferences.some((row) => row.channel === MAIL_CHANNEL && !row.enabled);
212
+ const external = preferences.filter((row) => row.enabled &&
213
+ row.address &&
214
+ // Only a number confirmed by its one-time code receives messages.
215
+ row.confirmed_at &&
216
+ row.channel !== MAIL_CHANNEL &&
217
+ row.channel !== IN_APP_CHANNEL);
218
+ const insert = async (trx) => {
219
+ const [row] = await trx('notifications')
220
+ .insert({
221
+ user_id: userId,
222
+ title: message.subject,
223
+ body: message.body,
224
+ template_key: key,
225
+ mail_state: message.mail ? (mailOff ? 'skipped' : 'pending') : null,
226
+ ...targetColumns(target),
227
+ })
228
+ .returning('id');
229
+ if (external.length)
230
+ await trx('notification_deliveries').insert(external.map((preference) => ({
231
+ id: randomUUID(),
232
+ notification_id: row.id,
233
+ channel: preference.channel,
234
+ })));
235
+ };
236
+ // The row and its deliveries commit together; a caller's transaction is used as-is.
237
+ if (!external.length || db.isTransaction)
238
+ await insert(db);
239
+ else
240
+ await db.transaction(insert);
180
241
  }
181
242
  /**
182
243
  * Delivers pending notification e-mails. Rows are claimed with SKIP LOCKED so
@@ -16,7 +16,8 @@ export async function seedModules(db, registry, actorId) {
16
16
  group,
17
17
  key: row.key,
18
18
  label_ar: row.label.ar,
19
- label_en: row.label.en,
19
+ // label_en is NOT NULL; an Arabic-only lookup shows its Arabic text there.
20
+ label_en: row.label.en ?? row.label.ar,
20
21
  sort: row.sort ?? index,
21
22
  active: true,
22
23
  })
@@ -0,0 +1,235 @@
1
+ import type { Knex } from 'knex';
2
+ import { IN_APP_CHANNEL, MAIL_CHANNEL, type MailSender } from './message_templates.js';
3
+ import { type HttpPoster, type SecretBox } from '../integrations/webhooks.js';
4
+ import { type OutboundOptions } from '../integrations/outbound.js';
5
+ import type { NotificationTarget } from '../services/settings.js';
6
+ export { IN_APP_CHANNEL, MAIL_CHANNEL };
7
+ export type ChannelLabel = {
8
+ ar: string;
9
+ en?: string;
10
+ };
11
+ /** The notification as a channel sends it. */
12
+ export type ChannelMessage = {
13
+ id: number;
14
+ subject: string;
15
+ text: string;
16
+ target: NotificationTarget | null;
17
+ };
18
+ export type ChannelRecipient = {
19
+ userId: number;
20
+ email: string;
21
+ name: string | null;
22
+ /** The address the user entered for the channel (a phone number); null for e-mail. */
23
+ address: string | null;
24
+ };
25
+ export type ChannelContext = {
26
+ /** Stable across retries; receivers deduplicate on it. */
27
+ deliveryId: string;
28
+ attempt: number;
29
+ signal: AbortSignal;
30
+ };
31
+ /**
32
+ * When a channel receives a notification:
33
+ * - 'always': in-app, the notification row itself; it cannot be turned off.
34
+ * - 'template': templates with external delivery (their mail flag), unless the user turned it off.
35
+ * - 'opt-in': the same templates, once the user enables the channel with an address.
36
+ */
37
+ export type ChannelDelivery = 'always' | 'template' | 'opt-in';
38
+ export interface NotificationChannel {
39
+ key: string;
40
+ label: ChannelLabel;
41
+ delivery: ChannelDelivery;
42
+ /** Normalizes the per-user address of an opt-in channel; throws AdulaError when invalid. */
43
+ address?(value: unknown): string;
44
+ /**
45
+ * Sends one message. Throw ChannelDeliveryError to name the failure category; other
46
+ * errors are categorized by outboundErrorCategory. Messages are never stored.
47
+ */
48
+ deliver(message: ChannelMessage, recipient: ChannelRecipient, context: ChannelContext): Promise<void>;
49
+ /**
50
+ * How the channel claims pending work. Without it, the dispatcher claims the channel's
51
+ * notification_deliveries rows (SKIP LOCKED and leased), calls deliver and retries
52
+ * failures with backoff. A channel with its own queue drains it here instead
53
+ * (e-mail: notifications.mail_state through deliverNotificationMail).
54
+ */
55
+ drain?(db: Knex, limit: number): Promise<{
56
+ sent: number;
57
+ failed: number;
58
+ }>;
59
+ }
60
+ export type ChannelPreference = {
61
+ key: string;
62
+ label: ChannelLabel;
63
+ delivery: ChannelDelivery;
64
+ enabled: boolean;
65
+ address: string | null;
66
+ /** In-app notifications cannot be turned off. */
67
+ locked: boolean;
68
+ };
69
+ export type ChannelPreferenceInput = {
70
+ key: unknown;
71
+ enabled: unknown;
72
+ address?: unknown;
73
+ };
74
+ export type ChannelDispatchResult = {
75
+ sent: number;
76
+ failed: number;
77
+ skipped: number;
78
+ };
79
+ /** A failed delivery with the category stored for it (for example `http-status:503`). */
80
+ export declare class ChannelDeliveryError extends Error {
81
+ category: string;
82
+ constructor(category: string);
83
+ }
84
+ export declare const CHANNEL_MAX_ATTEMPTS: number;
85
+ /** The in-app channel: the notifications row itself, listed and read in the bell. */
86
+ export declare function inAppChannel(): NotificationChannel;
87
+ /** The e-mail channel over the existing notifications.mail_state queue. */
88
+ export declare function mailChannel(send: MailSender): NotificationChannel;
89
+ /** An international phone number: an optional + and 8–15 digits; spaces and dashes are dropped. */
90
+ export declare function phoneAddress(value: unknown): string;
91
+ export type HttpChannelOptions = {
92
+ key: string;
93
+ label?: ChannelLabel;
94
+ url: string;
95
+ /** The signing secret; null when it cannot be opened (deliveries fail with `secret`). */
96
+ secret: string | null;
97
+ /** The guarded outbound client; defaults to createOutboundPoster() (public HTTPS only). */
98
+ post?: HttpPoster;
99
+ /** An absolute link to the notification's record, when it has one. */
100
+ link?: (target: NotificationTarget) => string | null;
101
+ timeoutMs?: number;
102
+ };
103
+ /**
104
+ * A pluggable HTTP provider channel (SMS, WhatsApp or any gateway): POSTs a JSON body
105
+ * `{ id, channel, to, subject, text, link?, timestamp }` signed like webhooks
106
+ * (X-Adula-Signature: sha256=hex HMAC-SHA256 over `${timestamp}.${body}`). A 2xx answer
107
+ * is sent; anything else is retried. Response bodies are never read.
108
+ */
109
+ export declare function httpNotificationChannel(options: HttpChannelOptions): NotificationChannel;
110
+ /**
111
+ * The channel registry and dispatcher. The worker calls deliver() on every tick; the
112
+ * profile screen reads and writes the signed-in user's preferences through it.
113
+ * In-app is always registered.
114
+ */
115
+ export declare class NotificationChannels {
116
+ private db;
117
+ private channels;
118
+ private retired;
119
+ constructor(db: Knex, channels?: NotificationChannel[],
120
+ /**
121
+ * `retired`: channel keys a successful configuration read proved are off (the
122
+ * provider is disabled or set to another kind). Their pending deliveries are skipped;
123
+ * pending rows of any other unregistered channel wait, so a failed read drops nothing.
124
+ */
125
+ options?: {
126
+ retired?: string[];
127
+ });
128
+ list(): {
129
+ key: string;
130
+ label: ChannelLabel;
131
+ delivery: ChannelDelivery;
132
+ }[];
133
+ get(key: string): NotificationChannel | undefined;
134
+ /** The user's choice per registered channel; absent rows are the defaults. */
135
+ preferences(userId: number, db?: Knex): Promise<ChannelPreference[]>;
136
+ /** Replaces the user's choices for the channels named in the input. */
137
+ update(userId: number, input: unknown): Promise<ChannelPreference[]>;
138
+ /**
139
+ * Sends a one-time code to `address` through the channel itself. The number is enabled
140
+ * only by confirmCode(). One code per user and channel at a time, a new one after 60
141
+ * seconds and at most five in 24 hours; the wait and the cap are enforced by the upsert
142
+ * itself, so two parallel requests send one code.
143
+ */
144
+ requestCode(userId: number, key: string, address: unknown): Promise<{
145
+ expiresAt: string;
146
+ }>;
147
+ /**
148
+ * Checks the code (five attempts, ten minutes) and enables the channel with its number.
149
+ * A used or exhausted code is voided, not deleted, so the wait and the daily cap remain.
150
+ */
151
+ confirmCode(userId: number, key: string, code: unknown): Promise<ChannelPreference[]>;
152
+ /** Deletes spent confirmation rows a day after they expired, with their numbers. */
153
+ cleanupConfirmations(): Promise<number>;
154
+ private optIn;
155
+ /**
156
+ * Delivers pending work on every registered channel. Pending rows of a retired channel
157
+ * (its provider was turned off) are skipped, never sent later; rows of a channel that is
158
+ * merely unregistered on this tick stay pending.
159
+ * `limit` bounds the claimed notification_deliveries rows, `drainLimit` each own queue
160
+ * (the e-mail worker sends up to 50 per tick, as before).
161
+ */
162
+ deliver(limit?: number, drainLimit?: number): Promise<ChannelDispatchResult>;
163
+ }
164
+ export declare const HTTP_CHANNEL_SETTING_KEY = "channels.http";
165
+ export declare const HTTP_CHANNEL_KINDS: readonly ["sms", "whatsapp"];
166
+ export type HttpChannelKind = (typeof HTTP_CHANNEL_KINDS)[number];
167
+ export declare const CHANNEL_KIND_LABELS: Record<string, ChannelLabel>;
168
+ /** The provider configuration as the settings screen shows it; the secret never leaves. */
169
+ export type HttpChannelConfig = {
170
+ enabled: boolean;
171
+ kind: HttpChannelKind;
172
+ url: string;
173
+ hasSecret: boolean;
174
+ updatedAt: string | null;
175
+ };
176
+ export type HttpChannelInput = {
177
+ enabled: unknown;
178
+ kind: unknown;
179
+ url: unknown;
180
+ };
181
+ /**
182
+ * The administrator-configured HTTP provider channel, stored in the system setting
183
+ * `channels.http` as `{ enabled, kind, url, secret, updatedAt }` with the signing secret
184
+ * sealed like webhook secrets. The secret is generated on first save and on rotation,
185
+ * returned once and never again; the settings screen lists the key without it.
186
+ */
187
+ export declare class HttpChannelSettings {
188
+ private db;
189
+ private secrets;
190
+ private options;
191
+ constructor(db: Knex, secrets: SecretBox, options?: OutboundOptions);
192
+ read(): Promise<HttpChannelConfig | null>;
193
+ private present;
194
+ /** Saves the provider; returns the new secret when one was generated (first save or rotate). */
195
+ save(actorId: number, input: HttpChannelInput, options?: {
196
+ rotate?: boolean;
197
+ }): Promise<{
198
+ config: HttpChannelConfig;
199
+ secret: string | null;
200
+ }>;
201
+ /** Replaces the signing secret and returns the new one once. */
202
+ rotate(actorId: number): Promise<{
203
+ config: HttpChannelConfig;
204
+ secret: string | null;
205
+ }>;
206
+ /** The configured channel while it is enabled; null otherwise. */
207
+ channel(options?: {
208
+ post?: HttpPoster;
209
+ link?: HttpChannelOptions['link'];
210
+ force?: boolean;
211
+ }): Promise<NotificationChannel | null>;
212
+ /**
213
+ * One read for the worker: the active channel (or null) and the HTTP channel kinds this
214
+ * read proves are off (no provider or disabled: every kind; enabled: the other kinds).
215
+ * Pass `retired` to NotificationChannels only after this call succeeded.
216
+ */
217
+ resolve(options?: {
218
+ post?: HttpPoster;
219
+ link?: HttpChannelOptions['link'];
220
+ }): Promise<{
221
+ channel: NotificationChannel | null;
222
+ retired: string[];
223
+ }>;
224
+ private build;
225
+ /**
226
+ * Sends one test message to `to` through the configured provider (enabled or not) and
227
+ * returns the failure category, or null when the provider accepted it.
228
+ */
229
+ test(to: unknown, options?: {
230
+ post?: HttpPoster;
231
+ }): Promise<string | null>;
232
+ private stored;
233
+ /** HTTPS only, and no host resolving to a private address unless the policy allows it. */
234
+ private assertTarget;
235
+ }