adula 2.1.0 → 2.3.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 (269) hide show
  1. package/README.md +149 -18
  2. package/build/agent/AGENTS.template.md +4 -4
  3. package/build/agent/capabilities.md +22 -12
  4. package/build/agent/skills/adula-frontend-design/SKILL.md +6 -4
  5. package/build/agent/skills/idea-review/SKILL.md +2 -2
  6. package/build/commands/adula_assistant_prune.d.ts +10 -0
  7. package/build/commands/adula_assistant_prune.js +12 -0
  8. package/build/commands/adula_outbox.d.ts +10 -0
  9. package/build/commands/adula_outbox.js +11 -0
  10. package/build/commands/adula_restore_reconcile.d.ts +10 -0
  11. package/build/commands/adula_restore_reconcile.js +34 -0
  12. package/build/commands/adula_runtime_health.d.ts +10 -0
  13. package/build/commands/adula_runtime_health.js +27 -0
  14. package/build/commands/adula_uploads_prune.d.ts +10 -0
  15. package/build/commands/adula_uploads_prune.js +16 -0
  16. package/build/commands/app.d.ts +10 -0
  17. package/build/commands/app.js +64 -0
  18. package/build/commands/backup_create.d.ts +11 -0
  19. package/build/commands/backup_create.js +99 -0
  20. package/build/commands/backup_open.d.ts +16 -0
  21. package/build/commands/backup_open.js +48 -0
  22. package/build/commands/backup_restore_files.d.ts +11 -0
  23. package/build/commands/backup_restore_files.js +44 -0
  24. package/build/commands/backup_restore_test.d.ts +12 -0
  25. package/build/commands/backup_restore_test.js +188 -0
  26. package/build/commands/backup_seal.d.ts +12 -0
  27. package/build/commands/backup_seal.js +36 -0
  28. package/build/commands/backup_services.d.ts +33 -0
  29. package/build/commands/backup_services.js +6 -0
  30. package/build/commands/backup_verify.d.ts +9 -0
  31. package/build/commands/backup_verify.js +59 -0
  32. package/build/commands/backup_verify_snapshot.d.ts +10 -0
  33. package/build/commands/backup_verify_snapshot.js +37 -0
  34. package/build/commands/client.d.ts +16 -0
  35. package/build/commands/client.js +71 -0
  36. package/build/commands/doctor.js +21 -1
  37. package/build/commands/install.d.ts +8 -0
  38. package/build/commands/install.js +69 -45
  39. package/build/commands/main.d.ts +3 -2
  40. package/build/commands/main.js +32 -0
  41. package/build/commands/module_add.js +4 -20
  42. package/build/commands/resource.d.ts +2 -0
  43. package/build/commands/resource.js +12 -3
  44. package/build/commands/resource_migration.d.ts +15 -0
  45. package/build/commands/resource_migration.js +81 -0
  46. package/build/commands/resource_snapshot.d.ts +2 -0
  47. package/build/commands/resource_snapshot.js +21 -4
  48. package/build/commands/sla_evaluate.d.ts +14 -0
  49. package/build/commands/sla_evaluate.js +16 -0
  50. package/build/commands/ui.js +4 -2
  51. package/build/commands/ui_css.d.ts +9 -0
  52. package/build/commands/ui_css.js +19 -0
  53. package/build/commands/upgrade.d.ts +1 -1
  54. package/build/commands/upgrade.js +1 -1
  55. package/build/configure.js +1 -1
  56. package/build/database/migrations/1770000000020_two_factor.d.ts +5 -0
  57. package/build/database/migrations/1770000000020_two_factor.js +10 -0
  58. package/build/database/migrations/1770000000041_import_modes.d.ts +5 -0
  59. package/build/database/migrations/1770000000041_import_modes.js +10 -0
  60. package/build/database/migrations/1770000000042_sync_jobs.d.ts +5 -0
  61. package/build/database/migrations/1770000000042_sync_jobs.js +10 -0
  62. package/build/database/migrations/1770000000043_notification_channels.d.ts +5 -0
  63. package/build/database/migrations/1770000000043_notification_channels.js +10 -0
  64. package/build/database/migrations/1770000000044_channel_confirmations.d.ts +5 -0
  65. package/build/database/migrations/1770000000044_channel_confirmations.js +10 -0
  66. package/build/database/migrations/1770000000045_import_leases.d.ts +5 -0
  67. package/build/database/migrations/1770000000045_import_leases.js +10 -0
  68. package/build/database/migrations/1770000000046_workflow_delegation_sla.d.ts +5 -0
  69. package/build/database/migrations/1770000000046_workflow_delegation_sla.js +10 -0
  70. package/build/database/migrations/1770000000049_print_templates.d.ts +5 -0
  71. package/build/database/migrations/1770000000049_print_templates.js +10 -0
  72. package/build/database/migrations/1770000000051_comment_notifications.d.ts +5 -0
  73. package/build/database/migrations/1770000000051_comment_notifications.js +10 -0
  74. package/build/database/migrations/1770000000054_cloud_backups.d.ts +5 -0
  75. package/build/database/migrations/1770000000054_cloud_backups.js +10 -0
  76. package/build/database/migrations/1770000000055_ai_assistant.d.ts +5 -0
  77. package/build/database/migrations/1770000000055_ai_assistant.js +10 -0
  78. package/build/database/migrations/1770000000056_appearance.d.ts +5 -0
  79. package/build/database/migrations/1770000000056_appearance.js +10 -0
  80. package/build/index.d.ts +87 -11
  81. package/build/index.js +50 -7
  82. package/build/providers/adula_provider.d.ts +2 -0
  83. package/build/providers/adula_provider.js +7 -0
  84. package/build/src/admin/contracts.js +1 -1
  85. package/build/src/admin/controller.d.ts +14 -1
  86. package/build/src/admin/controller.js +91 -13
  87. package/build/src/admin/errors.d.ts +32 -0
  88. package/build/src/admin/errors.js +63 -1
  89. package/build/src/admin/presentation.d.ts +21 -2
  90. package/build/src/admin/resource/editor.d.ts +60 -0
  91. package/build/src/admin/resource/editor.js +345 -0
  92. package/build/src/admin/resource/export.d.ts +54 -0
  93. package/build/src/admin/resource/export.js +262 -0
  94. package/build/src/admin/resource/lifecycle.d.ts +23 -0
  95. package/build/src/admin/resource/lifecycle.js +91 -0
  96. package/build/src/admin/resource/query.d.ts +111 -0
  97. package/build/src/admin/resource/query.js +595 -0
  98. package/build/src/admin/resource/read.d.ts +109 -0
  99. package/build/src/admin/resource/read.js +388 -0
  100. package/build/src/admin/resource/shared.d.ts +93 -0
  101. package/build/src/admin/resource/shared.js +265 -0
  102. package/build/src/admin/resource/trash.d.ts +10 -0
  103. package/build/src/admin/resource/trash.js +56 -0
  104. package/build/src/admin/resource/write.d.ts +57 -0
  105. package/build/src/admin/resource/write.js +603 -0
  106. package/build/src/admin/resource_service.d.ts +80 -193
  107. package/build/src/admin/resource_service.js +81 -1343
  108. package/build/src/admin/resource_tools.d.ts +111 -0
  109. package/build/src/admin/resource_tools.js +139 -0
  110. package/build/src/ai/assistant.d.ts +100 -0
  111. package/build/src/ai/assistant.js +487 -0
  112. package/build/src/ai/client.d.ts +49 -0
  113. package/build/src/ai/client.js +85 -0
  114. package/build/src/ai/prompt.d.ts +23 -0
  115. package/build/src/ai/prompt.js +83 -0
  116. package/build/src/ai/settings.d.ts +56 -0
  117. package/build/src/ai/settings.js +214 -0
  118. package/build/src/ai/usage.d.ts +16 -0
  119. package/build/src/ai/usage.js +33 -0
  120. package/build/src/appearance/appearance.d.ts +134 -0
  121. package/build/src/appearance/appearance.js +461 -0
  122. package/build/src/appearance/colors.d.ts +43 -0
  123. package/build/src/appearance/colors.js +99 -0
  124. package/build/src/appearance/logo.d.ts +32 -0
  125. package/build/src/appearance/logo.js +112 -0
  126. package/build/src/attachments/attachment_service.d.ts +46 -2
  127. package/build/src/attachments/attachment_service.js +96 -4
  128. package/build/src/auth/actor_store.d.ts +5 -1
  129. package/build/src/auth/actor_store.js +8 -4
  130. package/build/src/auth/conditions.d.ts +5 -0
  131. package/build/src/auth/conditions.js +26 -3
  132. package/build/src/auth/sql.js +17 -5
  133. package/build/src/auth/two_factor.d.ts +96 -0
  134. package/build/src/auth/two_factor.js +259 -0
  135. package/build/src/backups/archive.d.ts +52 -0
  136. package/build/src/backups/archive.js +362 -0
  137. package/build/src/backups/cloud_backups.d.ts +133 -0
  138. package/build/src/backups/cloud_backups.js +650 -0
  139. package/build/src/backups/doctor.d.ts +7 -0
  140. package/build/src/backups/doctor.js +55 -0
  141. package/build/src/backups/providers.d.ts +81 -0
  142. package/build/src/backups/providers.js +470 -0
  143. package/build/src/collaboration/assignments.d.ts +59 -2
  144. package/build/src/collaboration/assignments.js +196 -74
  145. package/build/src/collaboration/record_collaboration.d.ts +21 -4
  146. package/build/src/collaboration/record_collaboration.js +126 -51
  147. package/build/src/collaboration/shared.d.ts +24 -0
  148. package/build/src/collaboration/shared.js +34 -0
  149. package/build/src/commands/app_scaffold.d.ts +72 -0
  150. package/build/src/commands/app_scaffold.js +285 -0
  151. package/build/src/commands/capabilities.js +35 -9
  152. package/build/src/commands/doctor.d.ts +24 -2
  153. package/build/src/commands/doctor.js +81 -6
  154. package/build/src/commands/gap_report.d.ts +1 -1
  155. package/build/src/commands/gap_report.js +2 -2
  156. package/build/src/commands/generator.d.ts +37 -1
  157. package/build/src/commands/generator.js +61 -18
  158. package/build/src/commands/snapshot.d.ts +24 -13
  159. package/build/src/commands/snapshot.js +54 -14
  160. package/build/src/commands/source_markers.d.ts +10 -0
  161. package/build/src/commands/source_markers.js +29 -0
  162. package/build/src/core/activity.d.ts +2 -0
  163. package/build/src/core/activity.js +7 -1
  164. package/build/src/core/administrators.d.ts +38 -0
  165. package/build/src/core/administrators.js +145 -0
  166. package/build/src/core/avatar_image.d.ts +33 -0
  167. package/build/src/core/avatar_image.js +278 -0
  168. package/build/src/core/html_sanitizer.d.ts +20 -0
  169. package/build/src/core/html_sanitizer.js +261 -0
  170. package/build/src/core/like.d.ts +5 -0
  171. package/build/src/core/like.js +5 -0
  172. package/build/src/core/lookups.d.ts +80 -0
  173. package/build/src/core/lookups.js +319 -0
  174. package/build/src/core/mail_settings.d.ts +83 -0
  175. package/build/src/core/mail_settings.js +274 -0
  176. package/build/src/core/mail_test.d.ts +16 -0
  177. package/build/src/core/mail_test.js +81 -6
  178. package/build/src/core/message_templates.d.ts +15 -2
  179. package/build/src/core/message_templates.js +81 -11
  180. package/build/src/core/module_seed.js +2 -1
  181. package/build/src/core/notification_channels.d.ts +235 -0
  182. package/build/src/core/notification_channels.js +660 -0
  183. package/build/src/core/roles.js +26 -9
  184. package/build/src/core/saved_views.d.ts +8 -1
  185. package/build/src/core/saved_views.js +91 -26
  186. package/build/src/core/sequences.d.ts +32 -0
  187. package/build/src/core/sequences.js +97 -0
  188. package/build/src/core/settings.d.ts +5 -0
  189. package/build/src/core/settings.js +31 -3
  190. package/build/src/core/template_language.d.ts +61 -0
  191. package/build/src/core/template_language.js +141 -0
  192. package/build/src/core/ui_preferences.d.ts +10 -0
  193. package/build/src/core/ui_preferences.js +15 -1
  194. package/build/src/core/user_avatars.d.ts +79 -0
  195. package/build/src/core/user_avatars.js +186 -0
  196. package/build/src/core/user_invitations.d.ts +5 -1
  197. package/build/src/core/user_invitations.js +7 -1
  198. package/build/src/core/user_preferences.d.ts +36 -0
  199. package/build/src/core/user_preferences.js +125 -0
  200. package/build/src/core/users.d.ts +2 -0
  201. package/build/src/core/users.js +5 -3
  202. package/build/src/database/calendar_days.d.ts +19 -0
  203. package/build/src/database/calendar_days.js +36 -0
  204. package/build/src/database/schema.d.ts +201 -2
  205. package/build/src/database/schema.js +713 -59
  206. package/build/src/database/schema_diff.d.ts +70 -0
  207. package/build/src/database/schema_diff.js +190 -0
  208. package/build/src/events/record_mutation.d.ts +2 -1
  209. package/build/src/events/record_mutation.js +1 -0
  210. package/build/src/integrations/api_client.d.ts +37 -0
  211. package/build/src/integrations/api_client.js +567 -0
  212. package/build/src/integrations/import_adapters.d.ts +37 -0
  213. package/build/src/integrations/import_adapters.js +35 -0
  214. package/build/src/integrations/imports.d.ts +130 -16
  215. package/build/src/integrations/imports.js +434 -73
  216. package/build/src/integrations/openapi.d.ts +3 -1
  217. package/build/src/integrations/openapi.js +465 -31
  218. package/build/src/integrations/outbound.d.ts +94 -0
  219. package/build/src/integrations/outbound.js +276 -0
  220. package/build/src/integrations/print.d.ts +22 -1
  221. package/build/src/integrations/print.js +68 -22
  222. package/build/src/integrations/print_templates.d.ts +216 -0
  223. package/build/src/integrations/print_templates.js +1017 -0
  224. package/build/src/integrations/sync_jobs.d.ts +139 -0
  225. package/build/src/integrations/sync_jobs.js +416 -0
  226. package/build/src/integrations/webhooks.d.ts +12 -12
  227. package/build/src/integrations/webhooks.js +34 -43
  228. package/build/src/integrations/xlsx.d.ts +41 -0
  229. package/build/src/integrations/xlsx.js +519 -0
  230. package/build/src/languages/ar.d.ts +11 -0
  231. package/build/src/languages/ar.js +358 -0
  232. package/build/src/languages/ar_ui.d.ts +461 -0
  233. package/build/src/languages/ar_ui.js +464 -0
  234. package/build/src/languages/catalog.d.ts +66 -0
  235. package/build/src/languages/catalog.js +152 -0
  236. package/build/src/languages/en.d.ts +7 -0
  237. package/build/src/languages/en.js +352 -0
  238. package/build/src/languages/en_ui.d.ts +3 -0
  239. package/build/src/languages/en_ui.js +458 -0
  240. package/build/src/languages/validation.d.ts +26 -0
  241. package/build/src/languages/validation.js +60 -0
  242. package/build/src/lists/bulk_actions.d.ts +89 -0
  243. package/build/src/lists/bulk_actions.js +268 -0
  244. package/build/src/lists/dashboards.d.ts +138 -0
  245. package/build/src/lists/dashboards.js +290 -0
  246. package/build/src/mcp/tools.js +9 -104
  247. package/build/src/resource/define_resource.d.ts +18 -1
  248. package/build/src/resource/define_resource.js +212 -18
  249. package/build/src/resource/definition.d.ts +44 -0
  250. package/build/src/resource/definition.js +171 -0
  251. package/build/src/resource/registry.js +15 -4
  252. package/build/src/resource/types.d.ts +313 -16
  253. package/build/src/resource/values.d.ts +56 -1
  254. package/build/src/resource/values.js +237 -5
  255. package/build/src/services/settings.d.ts +2 -0
  256. package/build/src/services/settings.js +5 -1
  257. package/build/src/upgrade/legacy.js +2 -2
  258. package/build/src/workflows/calendar.d.ts +9 -0
  259. package/build/src/workflows/calendar.js +44 -0
  260. package/build/src/workflows/define_workflow.d.ts +48 -3
  261. package/build/src/workflows/define_workflow.js +57 -13
  262. package/build/src/workflows/delegations.d.ts +107 -0
  263. package/build/src/workflows/delegations.js +326 -0
  264. package/build/src/workflows/engine.d.ts +80 -4
  265. package/build/src/workflows/engine.js +466 -86
  266. package/build/src/workflows/sla.d.ts +15 -0
  267. package/build/src/workflows/sla.js +8 -0
  268. package/build/stubs/resource_contract.txt +12 -1
  269. package/package.json +9 -2
@@ -2,9 +2,14 @@ import type { Knex } from 'knex';
2
2
  import type { LucidModel } from '@adonisjs/lucid/types/model';
3
3
  import type { WorkflowDefinition } from '../workflows/define_workflow.js';
4
4
  import type { Conditions } from '../auth/conditions.js';
5
+ /**
6
+ * A display label. Arabic is required: it is the base language of every system.
7
+ * Other languages are optional; a missing `label.<lang>` falls back to `label.ar`.
8
+ */
5
9
  export type Label = {
6
10
  ar: string;
7
- en: string;
11
+ en?: string;
12
+ [language: string]: string | undefined;
8
13
  };
9
14
  export type Action = 'view' | 'create' | 'update' | 'delete' | 'submit' | 'cancel' | 'amend';
10
15
  export type Scalar = string | number | boolean | null;
@@ -13,29 +18,201 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
13
18
  [key: string]: JsonValue;
14
19
  };
15
20
  export type SerializedRecord = Record<string, JsonValue>;
21
+ /** One choice of an enum or multiSelect field: the stored value and its display label. */
22
+ export type FieldOption = {
23
+ value: string;
24
+ label: Label;
25
+ };
26
+ /**
27
+ * Length limits and an anchored pattern of a text-like field. `pattern` is a RegExp
28
+ * source matched against the whole value, trimmed except for text (wrapped in `^(?:…)$`).
29
+ */
30
+ export type TextConstraints = {
31
+ /** Minimum length in characters. */
32
+ min?: number;
33
+ /**
34
+ * Maximum length in characters. The column caps it: 255 for string, 254 for email,
35
+ * 32 for phone and 2048 for url.
36
+ */
37
+ max?: number;
38
+ /** RegExp source the whole value must match (trimmed except for text): `'\\d{10}'` means ten digits. */
39
+ pattern?: string;
40
+ };
41
+ /**
42
+ * Numeric limits. Money limits are canonical minor units (integer strings or safe
43
+ * integers); decimal and percent limits are decimal strings or numbers.
44
+ */
45
+ export type NumberConstraints = {
46
+ /** Smallest allowed value. */
47
+ min?: number | string;
48
+ /** Largest allowed value. */
49
+ max?: number | string;
50
+ };
16
51
  export type Field = {
52
+ /** Field label in forms, list headers and messages. */
17
53
  label: Label;
54
+ /**
55
+ * Column name when it is not the snake_case form of the field key.
56
+ * @default the field key in snake_case
57
+ */
18
58
  column?: string;
59
+ /**
60
+ * A value is needed (at least one for multiSelect and manyToMany). The column is
61
+ * `NOT NULL` unless the field has `visibleWhen`.
62
+ * @default false
63
+ */
19
64
  required?: boolean;
65
+ /**
66
+ * A partial unique index over live rows (`WHERE deleted_at IS NULL`); on a submittable
67
+ * resource cancelled documents do not count. Not on multiSelect, manyToMany or hasMany.
68
+ * @default false
69
+ */
20
70
  unique?: boolean;
71
+ /**
72
+ * Allowed in the list `sort` parameter. Not on multiSelect, manyToMany or hasMany.
73
+ * @default false
74
+ */
21
75
  sortable?: boolean;
76
+ /**
77
+ * Part of the generated full-text search vector. Only string, text, email, url, phone,
78
+ * enum and lookup.
79
+ * @default false
80
+ */
22
81
  searchable?: boolean;
82
+ /**
83
+ * Offered as a list filter (`filters[key]=value`).
84
+ * @default false
85
+ */
23
86
  filterable?: boolean;
87
+ /**
88
+ * The actor permission level needed to see or write the field. A field listed in the
89
+ * resource's `hidden` needs at least 1.
90
+ * @default 0
91
+ */
24
92
  permissionLevel?: number;
93
+ /**
94
+ * Numbering sequence key; the next number is assigned on create and the field is not
95
+ * part of the form input.
96
+ */
25
97
  sequence?: string;
26
- } & ({
27
- type: 'string' | 'text' | 'integer' | 'money' | 'boolean' | 'date' | 'datetime' | 'json';
28
- } | {
98
+ /**
99
+ * Applied on create when the input omits the key (server side, before validation),
100
+ * prefilled in the create form, and the column default for scalar types. An array
101
+ * only for multiSelect. Not allowed on relations, attachments, json or sequences.
102
+ */
103
+ default?: Scalar | string[];
104
+ /**
105
+ * The field applies only while every named sibling field equals the value (or one of
106
+ * the listed values; a multiSelect sibling must contain it). While it does not apply
107
+ * the form hides the field, `required` is not enforced and the server stores null
108
+ * (an empty list for manyToMany), on create and on update alike, except that an
109
+ * update keeps the stored value of a field the actor may not write. Values are
110
+ * canonical values of the sibling (checked by defineResource), for example '12.50'
111
+ * for a decimal sibling with scale 2.
112
+ */
113
+ visibleWhen?: Record<string, Scalar | Scalar[]>;
114
+ } &
115
+ /** A single-line trimmed string, varchar(255). */
116
+ (({
117
+ type: 'string';
118
+ } & TextConstraints & {
119
+ /** Also check the value as an e-mail address, URL or phone number. */
120
+ format?: 'email' | 'url' | 'phone';
121
+ })
122
+ /**
123
+ * `text`: unlimited text, not trimmed. `email`: a trimmed, lower-case address.
124
+ * `url`: an absolute http(s) URL. `phone`: `+?digits`, 7 to 15 digits.
125
+ */
126
+ | ({
127
+ type: 'text' | 'email' | 'url' | 'phone';
128
+ } & TextConstraints)
129
+ /** `integer`: a whole number. `money`: an integer string of minor units (bigint). */
130
+ | ({
131
+ type: 'integer' | 'money';
132
+ } & NumberConstraints)
133
+ /** A fixed-point number; for `percent`, '12.50' means 12.5 %. */
134
+ | ({
135
+ /** numeric(precision, scale); the wire value is a decimal string with `scale` digits. */
136
+ type: 'decimal' | 'percent';
137
+ /**
138
+ * Total significant digits, 1 to 1000.
139
+ * @default 18 (decimal), 7 (percent)
140
+ */
141
+ precision?: number;
142
+ /**
143
+ * Fractional digits, 0 to `precision`.
144
+ * @default 2
145
+ */
146
+ scale?: number;
147
+ } & NumberConstraints)
148
+ /**
149
+ * `boolean`: true or false. `date`: a calendar date `YYYY-MM-DD`. `datetime`: a UTC
150
+ * ISO timestamp with milliseconds. `json`: any JSON value (jsonb).
151
+ */
152
+ | {
153
+ type: 'boolean' | 'date' | 'datetime' | 'json';
154
+ }
155
+ /** One value from `options`, stored as its `value`. */
156
+ | {
157
+ type: 'enum';
158
+ /** The choices; values are unique and at most 255 characters. */
159
+ options: FieldOption[];
160
+ }
161
+ /** Distinct values from `options` stored as a JSON array in `options` order; min/max count. */
162
+ | {
163
+ type: 'multiSelect';
164
+ /** The choices; values are unique and at most 255 characters. */
165
+ options: FieldOption[];
166
+ /** Minimum number of selected values. */
167
+ min?: number;
168
+ /** Maximum number of selected values. */
169
+ max?: number;
170
+ }
171
+ /**
172
+ * Records of another resource linked through a join table (not a column). The value is
173
+ * the array of linked ids; the actor must be able to view every record they add.
174
+ */
175
+ | {
176
+ type: 'manyToMany';
177
+ /** Name of the linked resource. */
178
+ resource: string;
179
+ /**
180
+ * Join table name.
181
+ * @default `<owner table>_<field key in snake_case>`
182
+ */
183
+ table?: string;
184
+ }
185
+ /** Uploaded files: the id of one attachments row, or a JSON array of ids when `multiple`. */
186
+ | {
29
187
  type: 'attachment';
30
188
  /**
31
- * Lower-case file extensions accepted for upload, or 'any'. Defaults to
32
- * DEFAULT_ATTACHMENT_EXTENSIONS (documents, images and archives).
189
+ * Lower-case file extensions accepted for upload, or 'any'.
190
+ * DEFAULT_ATTACHMENT_EXTENSIONS lists documents, images and archives.
191
+ * @default DEFAULT_ATTACHMENT_EXTENSIONS
33
192
  */
34
193
  accept?: string[] | 'any';
35
- /** Upload size limit such as '5mb'. Defaults to '20mb'. */
194
+ /**
195
+ * Upload size limit of each file, such as '5mb'.
196
+ * @default '20mb'
197
+ */
36
198
  maxSize?: string;
37
- } | {
199
+ /**
200
+ * Several files per record (ADR 047): the column is a JSON array of attachment ids in
201
+ * display order; reads return the summaries in that order. Cannot be switched on or
202
+ * off for an existing column.
203
+ * @default false
204
+ */
205
+ multiple?: boolean;
206
+ /**
207
+ * Most files of a multiple field, from 1 to 100.
208
+ * @default MULTIPLE_ATTACHMENT_LIMIT
209
+ */
210
+ max?: number;
211
+ }
212
+ /** A record of another resource (integer foreign key, `RESTRICT`). */
213
+ | {
38
214
  type: 'belongsTo';
215
+ /** Name of the target resource. */
39
216
  resource: string;
40
217
  }
41
218
  /**
@@ -44,16 +221,62 @@ export type Field = {
44
221
  */
45
222
  | {
46
223
  type: 'user';
47
- } | {
224
+ }
225
+ /** Child records of another resource that point back to this one (no column). */
226
+ | {
48
227
  type: 'hasMany';
228
+ /** Name of the child resource. */
49
229
  resource: string;
230
+ /** The child's belongsTo field key that references this record. */
50
231
  foreignKey: string;
232
+ /**
233
+ * Edit the child rows inside the parent form; they are saved in the parent's
234
+ * transaction.
235
+ * @default false
236
+ */
51
237
  inline?: boolean;
52
- } | {
238
+ }
239
+ /** A key of a lookup group managed on /admin/lookups. */
240
+ | {
53
241
  type: 'lookup';
242
+ /** Lookup group key, for example one declared in the module's `lookups`. */
54
243
  group: string;
55
244
  });
245
+ export type PrintPaper = 'A4' | 'A5' | 'Letter';
246
+ export type PrintOrientation = 'portrait' | 'landscape';
247
+ /** A total line of a print template: a stored record field, or the sum of a line column. */
248
+ export type PrintTotal = {
249
+ label: Label;
250
+ field: string;
251
+ } | {
252
+ label: Label;
253
+ lines: string;
254
+ column: string;
255
+ };
256
+ /**
257
+ * A print layout declared with the resource (ADR 048). Fields and line columns are
258
+ * printed only when the reader may read them; `header` and `footer` are plain text that
259
+ * may use `{{id}}`, `{{company}}` and `{{field.key}}` placeholders.
260
+ */
261
+ export type PrintTemplate = {
262
+ /** Stable key used by `?template=<key>`; lower case, not `default`. */
263
+ key: string;
264
+ label: Label;
265
+ /** Defaults to A4. */
266
+ paper?: PrintPaper;
267
+ /** Defaults to portrait. */
268
+ orientation?: PrintOrientation;
269
+ header?: string;
270
+ footer?: string;
271
+ /** Record fields in print order (not hasMany). */
272
+ fields: readonly string[];
273
+ /** hasMany fields of the resource and the child columns to print for each. */
274
+ lines?: Readonly<Record<string, readonly string[]>>;
275
+ /** Money or number totals: a record field, or the sum of a printed line column. */
276
+ totals?: readonly PrintTotal[];
277
+ };
56
278
  export type Resource = {
279
+ /** Table and resource name: a lower-case letter, then lower-case letters, digits and `_`; at most 63 characters. */
57
280
  name: string;
58
281
  /** The list heading, usually plural (for example «الحسابات»). */
59
282
  label: Label;
@@ -64,7 +287,12 @@ export type Resource = {
64
287
  recordLabel?: Label;
65
288
  /** Full create-button text when «إضافة <recordLabel>» does not fit (for example «مهمة جديدة»). */
66
289
  createLabel?: Label;
67
- model: LucidModel;
290
+ /**
291
+ * Optional: AdulaJS persists through Knex and never reads it. Applications that use
292
+ * Lucid models in their own code may keep declaring it.
293
+ */
294
+ model?: LucidModel;
295
+ /** `true` adds `org_unit_id`: records belong to an organization unit and follow its scope. */
68
296
  scoped: boolean;
69
297
  /**
70
298
  * The organization unit of a scoped record follows a required belongsTo parent, for
@@ -75,30 +303,78 @@ export type Resource = {
75
303
  scope?: {
76
304
  from: string;
77
305
  };
306
+ /**
307
+ * Records are documents: draft, submit, cancel and amend-by-copy, with workflows.
308
+ * @default false
309
+ */
78
310
  submittable?: boolean;
311
+ /**
312
+ * Optimistic versions: updates send the current version and stale writes are 409.
313
+ * @default the value of `submittable`
314
+ */
79
315
  version?: boolean;
80
- customFields?: boolean;
316
+ /** The fields by key (camelCase; the column is the snake_case key unless `column` is set). */
81
317
  fields: Record<string, Field>;
318
+ /** Field keys shown as list columns, in order. */
82
319
  list: readonly string[];
320
+ /**
321
+ * The list's order when the user has chosen none: a sortable field (or `id`) and its
322
+ * direction (ascending unless given). Ties are broken by id in the same direction.
323
+ * @default newest first: created_at descending, then id descending
324
+ */
325
+ defaultSort?: {
326
+ field: string;
327
+ direction?: 'asc' | 'desc';
328
+ };
329
+ /** Field keys of the create and edit form, in order. */
83
330
  form: readonly string[];
331
+ /** Field keys of the record details view, in order. */
84
332
  show: readonly string[];
333
+ /**
334
+ * Field keys returned by reads and the API.
335
+ * @default the keys of `list` and `show`
336
+ */
85
337
  serialize?: readonly string[];
338
+ /** Field keys that need permission level 1 or more to see or write. */
86
339
  hidden?: readonly string[];
87
340
  /**
88
341
  * Fields that name a record wherever it is referenced: relation cells and pickers,
89
- * "My tasks" and the approvals inbox. Joined with « · ». Defaults to the first
90
- * sequence field and the first text field in `list`.
342
+ * "My tasks" and the approvals inbox. Joined with « · ».
343
+ * @default the first sequence field and the first text field in `list`
91
344
  */
92
345
  title?: readonly string[];
346
+ /**
347
+ * Operations the resource offers: view, create, update, delete, and submit, cancel and
348
+ * amend on a submittable resource. Role rules still decide who may use each one.
349
+ */
93
350
  actions: readonly Action[];
94
- validator: {
351
+ /**
352
+ * Field combinations that must be unique among live records (a partial unique index
353
+ * `WHERE deleted_at IS NULL`, and `AND doc_status <> 2` on a submittable resource so
354
+ * cancelled documents do not count), for example `[['customerId', 'code']]`. Every key
355
+ * is a stored field, or `orgUnitId` on a scoped resource (a code unique per unit).
356
+ */
357
+ unique?: readonly (readonly string[])[];
358
+ /**
359
+ * Optional: without it, writes are validated by the VineJS validator derived from the
360
+ * fields (see definitionValidator). A given validator replaces the derived one; field
361
+ * constraints are enforced again when values are stored, whatever the validator returns.
362
+ */
363
+ validator?: {
95
364
  validate(data: unknown): Promise<RecordData>;
96
365
  };
366
+ /**
367
+ * Printable layouts offered on the record page next to the generic print (ADR 048).
368
+ * Administrators add more in «قوالب الطباعة»; see PrintTemplates.
369
+ */
370
+ printTemplates?: readonly PrintTemplate[];
371
+ /** Functions called inside the write transaction, before and after a record is stored. */
97
372
  hooks?: {
98
373
  beforeSave?: (record: RecordData, context: HookContext) => Promise<void>;
99
374
  afterSave?: (record: RecordData, context: HookContext) => Promise<void>;
100
375
  };
101
376
  };
377
+ /** What a hook receives: the write transaction, the acting user's id and the action. */
102
378
  export type HookContext = {
103
379
  trx: Knex.Transaction;
104
380
  userId: number;
@@ -106,8 +382,11 @@ export type HookContext = {
106
382
  };
107
383
  /** A changeable list value a module needs before its records can be saved. */
108
384
  export type ModuleLookup = {
385
+ /** The stored value. */
109
386
  key: string;
387
+ /** Display label. */
110
388
  label: Label;
389
+ /** Position in the lookup's list. */
111
390
  sort?: number;
112
391
  };
113
392
  /** A role a module ships; its rules go through the same validation as the roles screen. */
@@ -116,7 +395,15 @@ export type ModuleRole = {
116
395
  key: string;
117
396
  /** Arabic display name; administrators may rename it later. */
118
397
  name: string;
398
+ /**
399
+ * Permission level of the role's holders (compared with Field.permissionLevel).
400
+ * @default 0
401
+ */
119
402
  permissionLevel?: number;
403
+ /**
404
+ * Role rules: `subject` is a resource name or 'all', `fields` limits a rule to those
405
+ * fields, `conditions` to matching records and `inverted` makes it a denial.
406
+ */
120
407
  rules: readonly {
121
408
  subject: string;
122
409
  action: string;
@@ -125,11 +412,20 @@ export type ModuleRole = {
125
412
  fields?: string[] | null;
126
413
  }[];
127
414
  };
415
+ /** One application of a system, exported by `app/modules/<name>/module.ts`. */
128
416
  export type Module = {
417
+ /** Module (application) name: its folder under app/modules. */
129
418
  name: string;
419
+ /**
420
+ * An example module that `adula:module:remove` may unregister and archive (its tables are kept).
421
+ * @default false
422
+ */
130
423
  reference?: boolean;
424
+ /** The application's menu group label. */
131
425
  label: Label;
426
+ /** Names of the modules whose resources this module's relations may reference. */
132
427
  dependsOn: readonly string[];
428
+ /** The module's resource definitions. */
133
429
  resources: readonly Resource[];
134
430
  /** Versioned workflows of this module's submittable resources (phase 4). */
135
431
  workflows?: readonly WorkflowDefinition[];
@@ -144,8 +440,9 @@ export type Module = {
144
440
  */
145
441
  defaultRoles?: readonly ModuleRole[];
146
442
  };
147
- export type ResourceInput<F extends Record<string, Field>> = Omit<Resource, 'fields' | 'list' | 'form' | 'show' | 'hidden' | 'serialize' | 'title'> & {
443
+ export type ResourceInput<F extends Record<string, Field>> = Omit<Resource, 'fields' | 'list' | 'form' | 'show' | 'hidden' | 'serialize' | 'title' | 'unique'> & {
148
444
  fields: F;
445
+ unique?: readonly (readonly ((keyof F & string) | 'orgUnitId')[])[];
149
446
  list: readonly (keyof F & string)[];
150
447
  form: readonly (keyof F & string)[];
151
448
  show: readonly (keyof F & string)[];
@@ -1,5 +1,60 @@
1
1
  import type { Field } from './types.js';
2
+ import { type MessageParams } from '../languages/catalog.js';
3
+ /**
4
+ * A value the field definition forbids. `rule` names the catalog message
5
+ * (`validation.<rule>`), so the derived VineJS validator reports it like its own rules.
6
+ */
7
+ export declare class FieldValueError extends Error {
8
+ readonly rule: string;
9
+ readonly params: MessageParams;
10
+ constructor(rule: string, params?: MessageParams);
11
+ }
12
+ /** Column length of each text-like type (string and enum are varchar(255)). */
13
+ export declare const TEXT_LIMITS: Readonly<Record<string, number>>;
14
+ /** The most ids one manyToMany write may link. */
15
+ export declare const MANY_TO_MANY_LIMIT = 500;
16
+ /** Files a multiple attachment field accepts when it declares no `max` (ADR 047). */
17
+ export declare const MULTIPLE_ATTACHMENT_LIMIT = 10;
18
+ /** The largest `max` a multiple attachment field may declare. */
19
+ export declare const MULTIPLE_ATTACHMENT_MAX = 100;
20
+ /** An attachment field holding several files: a JSON array of attachment ids, in order. */
21
+ export declare function isMultipleAttachment(field: Field | undefined): boolean;
22
+ /** The most files an attachment field accepts: one, or the `max` of a multiple field. */
23
+ export declare function attachmentLimit(field: Field): number;
24
+ /** numeric(precision, scale) of a decimal or percent field, with the documented defaults. */
25
+ export declare function decimalShape(field: {
26
+ type: string;
27
+ precision?: number;
28
+ scale?: number;
29
+ }): {
30
+ precision: number;
31
+ scale: number;
32
+ };
33
+ /**
34
+ * The canonical decimal string of a number or numeric string: an optional minus, the
35
+ * integer digits without leading zeros and exactly `scale` fractional digits ("12.50").
36
+ * Rejects more fractional digits than `scale` (trailing zeros excepted), more than
37
+ * `precision - scale` integer digits and JSON numbers beyond exact precision (see
38
+ * unsafeNumber); strings keep every digit.
39
+ */
40
+ export declare function canonicalDecimal(value: unknown, precision: number, scale: number): string;
41
+ /** Arabic-Indic and Extended Arabic-Indic digits as ASCII digits. */
42
+ export declare function latinDigits(value: string): string;
43
+ /** `+?digits` (7 to 15 digits) from input with spaces, dashes, dots, parentheses or Arabic digits. */
44
+ export declare function normalizePhone(value: string): string;
45
+ /** A trimmed, lower-cased e-mail address. */
46
+ export declare function normalizeEmail(value: string): string;
47
+ /** A trimmed absolute http(s) URL; javascript:, data: and relative URLs are refused. */
48
+ export declare function normalizeUrl(value: string): string;
49
+ /** The anchored RegExp of a field pattern (`^(?:source)$`), compiled once. */
50
+ export declare function fieldPattern(source: string): RegExp;
2
51
  export declare function canonicalDate(value: unknown, type: 'date' | 'datetime'): boolean;
3
52
  export declare function canonicalMoney(value: unknown): value is string;
4
- /** Normalize before CASL evaluates a prospective record, using its stored representation. */
53
+ /**
54
+ * Normalize before CASL evaluates a prospective record, using its stored representation.
55
+ * It is also the hard guarantee of the definition: every stored value passes here, so
56
+ * hooks, custom validators and system writes cannot store what a field forbids (length,
57
+ * pattern, format, options, numeric limits, decimal scale). Constraint violations of
58
+ * the field types and options added in 2.2 throw FieldValueError with a catalog message.
59
+ */
5
60
  export declare function fieldValue(field: Field, value: unknown): unknown;