adula 2.2.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 (132) hide show
  1. package/README.md +1 -1
  2. package/build/agent/capabilities.md +2 -3
  3. package/build/agent/skills/adula-frontend-design/SKILL.md +5 -3
  4. package/build/commands/adula_assistant_prune.d.ts +10 -0
  5. package/build/commands/adula_assistant_prune.js +12 -0
  6. package/build/commands/backup_open.d.ts +16 -0
  7. package/build/commands/backup_open.js +48 -0
  8. package/build/commands/backup_restore_test.js +3 -0
  9. package/build/commands/backup_seal.d.ts +12 -0
  10. package/build/commands/backup_seal.js +36 -0
  11. package/build/commands/backup_services.d.ts +3 -1
  12. package/build/commands/doctor.js +18 -1
  13. package/build/commands/install.js +6 -0
  14. package/build/commands/main.d.ts +2 -2
  15. package/build/commands/main.js +6 -0
  16. package/build/commands/resource_migration.js +12 -3
  17. package/build/commands/resource_snapshot.js +18 -4
  18. package/build/database/migrations/1770000000051_comment_notifications.d.ts +5 -0
  19. package/build/database/migrations/1770000000051_comment_notifications.js +10 -0
  20. package/build/database/migrations/1770000000054_cloud_backups.d.ts +5 -0
  21. package/build/database/migrations/1770000000054_cloud_backups.js +10 -0
  22. package/build/database/migrations/1770000000055_ai_assistant.d.ts +5 -0
  23. package/build/database/migrations/1770000000055_ai_assistant.js +10 -0
  24. package/build/database/migrations/1770000000056_appearance.d.ts +5 -0
  25. package/build/database/migrations/1770000000056_appearance.js +10 -0
  26. package/build/index.d.ts +36 -6
  27. package/build/index.js +18 -3
  28. package/build/src/admin/controller.js +18 -4
  29. package/build/src/admin/resource/editor.d.ts +1 -0
  30. package/build/src/admin/resource/editor.js +26 -4
  31. package/build/src/admin/resource/export.d.ts +21 -4
  32. package/build/src/admin/resource/export.js +117 -36
  33. package/build/src/admin/resource/lifecycle.d.ts +2 -0
  34. package/build/src/admin/resource/query.d.ts +14 -3
  35. package/build/src/admin/resource/query.js +98 -11
  36. package/build/src/admin/resource/read.d.ts +3 -0
  37. package/build/src/admin/resource/read.js +75 -14
  38. package/build/src/admin/resource/shared.d.ts +16 -0
  39. package/build/src/admin/resource/shared.js +47 -4
  40. package/build/src/admin/resource/write.js +37 -8
  41. package/build/src/admin/resource_service.d.ts +17 -3
  42. package/build/src/admin/resource_service.js +16 -2
  43. package/build/src/admin/resource_tools.d.ts +111 -0
  44. package/build/src/admin/resource_tools.js +139 -0
  45. package/build/src/ai/assistant.d.ts +100 -0
  46. package/build/src/ai/assistant.js +487 -0
  47. package/build/src/ai/client.d.ts +49 -0
  48. package/build/src/ai/client.js +85 -0
  49. package/build/src/ai/prompt.d.ts +23 -0
  50. package/build/src/ai/prompt.js +83 -0
  51. package/build/src/ai/settings.d.ts +56 -0
  52. package/build/src/ai/settings.js +214 -0
  53. package/build/src/ai/usage.d.ts +16 -0
  54. package/build/src/ai/usage.js +33 -0
  55. package/build/src/appearance/appearance.d.ts +134 -0
  56. package/build/src/appearance/appearance.js +461 -0
  57. package/build/src/appearance/colors.d.ts +43 -0
  58. package/build/src/appearance/colors.js +99 -0
  59. package/build/src/appearance/logo.d.ts +32 -0
  60. package/build/src/appearance/logo.js +112 -0
  61. package/build/src/auth/actor_store.d.ts +5 -1
  62. package/build/src/auth/actor_store.js +8 -4
  63. package/build/src/backups/archive.d.ts +52 -0
  64. package/build/src/backups/archive.js +362 -0
  65. package/build/src/backups/cloud_backups.d.ts +133 -0
  66. package/build/src/backups/cloud_backups.js +650 -0
  67. package/build/src/backups/doctor.d.ts +7 -0
  68. package/build/src/backups/doctor.js +55 -0
  69. package/build/src/backups/providers.d.ts +81 -0
  70. package/build/src/backups/providers.js +470 -0
  71. package/build/src/collaboration/assignments.d.ts +24 -2
  72. package/build/src/collaboration/assignments.js +88 -32
  73. package/build/src/collaboration/record_collaboration.d.ts +19 -1
  74. package/build/src/collaboration/record_collaboration.js +109 -37
  75. package/build/src/collaboration/shared.d.ts +10 -2
  76. package/build/src/collaboration/shared.js +14 -1
  77. package/build/src/commands/capabilities.js +1 -1
  78. package/build/src/commands/doctor.d.ts +10 -0
  79. package/build/src/commands/doctor.js +31 -1
  80. package/build/src/commands/snapshot.d.ts +14 -0
  81. package/build/src/commands/snapshot.js +23 -0
  82. package/build/src/core/administrators.js +19 -3
  83. package/build/src/core/avatar_image.d.ts +33 -0
  84. package/build/src/core/avatar_image.js +278 -0
  85. package/build/src/core/mail_settings.d.ts +83 -0
  86. package/build/src/core/mail_settings.js +274 -0
  87. package/build/src/core/mail_test.d.ts +16 -0
  88. package/build/src/core/mail_test.js +81 -6
  89. package/build/src/core/message_templates.d.ts +8 -0
  90. package/build/src/core/message_templates.js +12 -3
  91. package/build/src/core/roles.js +24 -7
  92. package/build/src/core/saved_views.js +55 -24
  93. package/build/src/core/settings.d.ts +2 -2
  94. package/build/src/core/settings.js +15 -4
  95. package/build/src/core/ui_preferences.d.ts +6 -0
  96. package/build/src/core/ui_preferences.js +12 -1
  97. package/build/src/core/user_avatars.d.ts +79 -0
  98. package/build/src/core/user_avatars.js +186 -0
  99. package/build/src/core/user_preferences.d.ts +36 -0
  100. package/build/src/core/user_preferences.js +125 -0
  101. package/build/src/core/users.d.ts +2 -0
  102. package/build/src/core/users.js +4 -2
  103. package/build/src/database/schema.d.ts +46 -0
  104. package/build/src/database/schema.js +182 -0
  105. package/build/src/database/schema_diff.d.ts +16 -2
  106. package/build/src/database/schema_diff.js +40 -7
  107. package/build/src/integrations/api_client.js +18 -3
  108. package/build/src/integrations/imports.d.ts +16 -4
  109. package/build/src/integrations/imports.js +36 -8
  110. package/build/src/integrations/openapi.js +15 -4
  111. package/build/src/integrations/outbound.d.ts +43 -0
  112. package/build/src/integrations/outbound.js +98 -17
  113. package/build/src/integrations/print.d.ts +2 -1
  114. package/build/src/integrations/print.js +7 -3
  115. package/build/src/integrations/print_templates.js +3 -1
  116. package/build/src/integrations/xlsx.d.ts +41 -0
  117. package/build/src/integrations/xlsx.js +519 -0
  118. package/build/src/languages/ar.js +22 -0
  119. package/build/src/languages/ar_ui.d.ts +143 -14
  120. package/build/src/languages/ar_ui.js +145 -14
  121. package/build/src/languages/en.js +22 -0
  122. package/build/src/languages/en_ui.js +144 -14
  123. package/build/src/lists/dashboards.d.ts +42 -0
  124. package/build/src/lists/dashboards.js +49 -0
  125. package/build/src/mcp/tools.js +9 -104
  126. package/build/src/resource/define_resource.js +7 -0
  127. package/build/src/resource/types.d.ts +9 -0
  128. package/build/src/workflows/delegations.d.ts +15 -1
  129. package/build/src/workflows/delegations.js +49 -10
  130. package/build/src/workflows/engine.d.ts +11 -0
  131. package/build/src/workflows/engine.js +29 -7
  132. package/package.json +5 -1
@@ -1008,3 +1008,185 @@ END
1008
1008
  $$ LANGUAGE plpgsql`);
1009
1009
  await db.raw('CREATE TRIGGER print_template_versions_immutable BEFORE UPDATE OR DELETE ON print_template_versions FOR EACH ROW EXECUTE FUNCTION adula_print_template_versions_immutable()');
1010
1010
  }
1011
+ /** Template keys of the notifications that quote a comment's text. */
1012
+ export const COMMENT_NOTIFICATION_KEYS = ['comment.mentioned', 'comment.created'];
1013
+ export const DELETED_COMMENT_TITLE = 'تعليق محذوف';
1014
+ export const DELETED_COMMENT_BODY = 'حُذف هذا التعليق.';
1015
+ /**
1016
+ * Ids and template keys of the notifications that quote a comment: those naming it
1017
+ * (comment_id, 2.3.0) and those written before notifications named their comment. A
1018
+ * comment's notifications were inserted in its own transaction, so their created_at equals
1019
+ * the comment's (both now()), and they quote its text from the start: the first 100
1020
+ * characters are matched, which the 200-unit excerpt always contains. Read before a
1021
+ * comment's body changes. `comment` is one comment id, or 'deleted' for every deleted one.
1022
+ */
1023
+ export async function commentNotifications(db, comment) {
1024
+ const result = await db.raw(`SELECT DISTINCT n.id, n.template_key FROM notifications n JOIN comments c
1025
+ ON n.comment_id = c.id OR (
1026
+ n.comment_id IS NULL AND n.template_key IN (?, ?) AND n.created_at = c.created_at
1027
+ AND (n.resource IS NULL OR (n.resource = c.resource AND n.record_id = c.record_id))
1028
+ AND (strpos(n.body, left(c.body, 100)) > 0 OR strpos(n.title, left(c.body, 100)) > 0))
1029
+ WHERE ${comment === 'deleted' ? 'c.deleted_at IS NOT NULL' : 'c.id = ?'}`, [...COMMENT_NOTIFICATION_KEYS, ...(comment === 'deleted' ? [] : [comment])]);
1030
+ return result.rows.map((row) => ({
1031
+ id: Number(row.id),
1032
+ key: String(row.template_key ?? ''),
1033
+ }));
1034
+ }
1035
+ /**
1036
+ * Stops what has not been sent yet of the given notifications: pending e-mail is skipped
1037
+ * and pending channel deliveries are withdrawn (a channel worker re-checks the pending
1038
+ * state before it sends, so a claimed delivery is not sent either).
1039
+ */
1040
+ export async function withdrawNotificationDelivery(db, ids) {
1041
+ if (!ids.length)
1042
+ return;
1043
+ await db('notifications').whereIn('id', ids).where('mail_state', 'pending').update({
1044
+ mail_state: 'skipped',
1045
+ });
1046
+ await db('notification_deliveries')
1047
+ .whereIn('notification_id', ids)
1048
+ .where('state', 'pending')
1049
+ .update({ state: 'skipped', error_category: 'withdrawn' });
1050
+ }
1051
+ /**
1052
+ * Comment notifications name their comment (2.3.0), so deleting or editing the comment
1053
+ * withdraws the quoted text. Notifications of comments deleted before this migration are
1054
+ * found by their transaction time and quoted text, and withdrawn here.
1055
+ */
1056
+ export async function createCommentNotificationsSchema(db) {
1057
+ await db.schema.alterTable('notifications', (t) => {
1058
+ t.bigInteger('comment_id').references('id').inTable('comments').onDelete('SET NULL');
1059
+ });
1060
+ await db.raw('CREATE INDEX notifications_comment_id ON notifications (comment_id) WHERE comment_id IS NOT NULL');
1061
+ await withdrawDeletedCommentNotifications(db);
1062
+ }
1063
+ /** Replaces the quoted text of every deleted comment's notifications with a neutral note. */
1064
+ export async function withdrawDeletedCommentNotifications(db) {
1065
+ const rows = await commentNotifications(db, 'deleted');
1066
+ const ids = rows.map((row) => row.id);
1067
+ for (let start = 0; start < ids.length; start += 1000) {
1068
+ const chunk = ids.slice(start, start + 1000);
1069
+ await db('notifications')
1070
+ .whereIn('id', chunk)
1071
+ .update({ title: DELETED_COMMENT_TITLE, body: DELETED_COMMENT_BODY });
1072
+ await withdrawNotificationDelivery(db, chunk);
1073
+ }
1074
+ }
1075
+ /**
1076
+ * The built-in assistant (ADR 052): conversation metadata (never message text), pending
1077
+ * write proposals awaiting the user's confirmation, and per-user daily token usage.
1078
+ */
1079
+ export async function createAssistantSchema(db) {
1080
+ await db.schema.createTable('ai_conversations', (t) => {
1081
+ // Integer: the id is the record_id of the conversation's activity entries.
1082
+ t.increments('id');
1083
+ t.integer('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
1084
+ t.integer('impersonator_id').references('id').inTable('users').onDelete('SET NULL');
1085
+ t.integer('turns').notNullable().defaultTo(0);
1086
+ t.integer('tokens').notNullable().defaultTo(0);
1087
+ t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
1088
+ t.timestamp('last_turn_at', { useTz: true });
1089
+ t.index(['user_id', 'created_at']);
1090
+ });
1091
+ await db.schema.createTable('ai_pending_actions', (t) => {
1092
+ t.uuid('id').primary();
1093
+ t.integer('conversation_id')
1094
+ .notNullable()
1095
+ .references('id')
1096
+ .inTable('ai_conversations')
1097
+ .onDelete('CASCADE');
1098
+ t.integer('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
1099
+ t.integer('impersonator_id');
1100
+ t.string('resource').notNullable();
1101
+ t.string('action').notNullable();
1102
+ t.integer('record_id');
1103
+ t.jsonb('input');
1104
+ t.integer('version');
1105
+ t.timestamp('expires_at', { useTz: true }).notNullable();
1106
+ t.timestamp('consumed_at', { useTz: true });
1107
+ t.string('outcome', 20);
1108
+ t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
1109
+ t.index(['user_id', 'consumed_at']);
1110
+ t.index(['expires_at']);
1111
+ });
1112
+ await db.schema.createTable('ai_usage', (t) => {
1113
+ t.integer('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
1114
+ t.date('day').notNullable();
1115
+ t.integer('prompt_tokens').notNullable().defaultTo(0);
1116
+ t.integer('completion_tokens').notNullable().defaultTo(0);
1117
+ t.integer('reserved').notNullable().defaultTo(0);
1118
+ t.integer('requests').notNullable().defaultTo(0);
1119
+ t.primary(['user_id', 'day']);
1120
+ });
1121
+ }
1122
+ /**
1123
+ * Cloud and downloadable backups (ADR 051): one connection per destination with its refresh
1124
+ * token sealed by the host's SecretBox, and one row per backup run.
1125
+ */
1126
+ export async function createCloudBackupsSchema(db) {
1127
+ await db.schema.createTable('backup_connections', (t) => {
1128
+ t.increments('id');
1129
+ t.string('provider', 20).notNullable().unique();
1130
+ t.string('status', 20).notNullable().defaultTo('connected');
1131
+ t.string('account_label', 320);
1132
+ t.text('refresh_token').notNullable();
1133
+ t.string('schedule', 10).notNullable().defaultTo('off');
1134
+ t.integer('connected_by').notNullable().references('id').inTable('users').onDelete('RESTRICT');
1135
+ t.timestamp('connected_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
1136
+ t.timestamp('updated_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
1137
+ });
1138
+ await db.raw(`ALTER TABLE backup_connections
1139
+ ADD CONSTRAINT backup_connections_provider CHECK (provider IN ('google', 'onedrive')),
1140
+ ADD CONSTRAINT backup_connections_status CHECK (status IN ('connected', 'revoked')),
1141
+ ADD CONSTRAINT backup_connections_schedule CHECK (schedule IN ('off', 'daily', 'weekly'))`);
1142
+ await db.schema.createTable('backup_runs', (t) => {
1143
+ t.bigIncrements('id');
1144
+ t.string('kind', 20).notNullable();
1145
+ t.integer('connection_id').references('id').inTable('backup_connections').onDelete('SET NULL');
1146
+ t.string('trigger', 10).notNullable().defaultTo('manual');
1147
+ t.string('status', 20).notNullable().defaultTo('queued');
1148
+ t.integer('requested_by').notNullable().references('id').inTable('users').onDelete('RESTRICT');
1149
+ t.string('file_name', 200);
1150
+ t.bigInteger('size_bytes');
1151
+ t.string('sha256', 64);
1152
+ t.string('remote_id', 500);
1153
+ t.timestamp('expires_at', { useTz: true });
1154
+ t.string('error_category', 40);
1155
+ t.string('error_message', 500);
1156
+ t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
1157
+ t.timestamp('started_at', { useTz: true });
1158
+ t.timestamp('finished_at', { useTz: true });
1159
+ });
1160
+ await db.raw(`ALTER TABLE backup_runs
1161
+ ADD CONSTRAINT backup_runs_kind CHECK (kind IN ('download', 'google', 'onedrive')),
1162
+ ADD CONSTRAINT backup_runs_trigger CHECK (trigger IN ('manual', 'schedule')),
1163
+ ADD CONSTRAINT backup_runs_status
1164
+ CHECK (status IN ('queued', 'running', 'succeeded', 'failed', 'expired'))`);
1165
+ await db.raw(`CREATE UNIQUE INDEX backup_runs_active ON backup_runs (kind) WHERE status IN ('queued', 'running')`);
1166
+ await db.raw('CREATE INDEX backup_runs_kind_created ON backup_runs (kind, created_at DESC)');
1167
+ }
1168
+ /**
1169
+ * Appearance occasions (ADR 053): dated overrides of the base identity, which is the system
1170
+ * setting `appearance.identity`. Logos are `attachments` rows, so only the id is kept here.
1171
+ * Overlapping ranges are refused by the service under a table lock.
1172
+ */
1173
+ export async function createAppearanceSchema(db) {
1174
+ await db.schema.createTable('appearance_occasions', (t) => {
1175
+ t.increments('id');
1176
+ t.string('name', 80).notNullable();
1177
+ t.date('starts_on').notNullable();
1178
+ t.date('ends_on').notNullable();
1179
+ t.string('primary_color', 7);
1180
+ t.integer('logo_id');
1181
+ t.string('banner', 160);
1182
+ t.string('login_title', 120);
1183
+ t.string('login_description', 300);
1184
+ t.integer('created_by').references('id').inTable('users').onDelete('SET NULL');
1185
+ t.integer('updated_by').references('id').inTable('users').onDelete('SET NULL');
1186
+ t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
1187
+ t.timestamp('updated_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
1188
+ t.index(['starts_on', 'ends_on']);
1189
+ });
1190
+ await db.raw('ALTER TABLE appearance_occasions ADD CONSTRAINT appearance_occasions_dates CHECK (ends_on >= starts_on)');
1191
+ await db.raw("ALTER TABLE appearance_occasions ADD CONSTRAINT appearance_occasions_color CHECK (primary_color IS NULL OR primary_color ~ '^#[0-9a-f]{6}$')");
1192
+ }
@@ -52,5 +52,19 @@ export declare function describeDrift(drift: SchemaDrift): string[];
52
52
  * hand-written migration.
53
53
  */
54
54
  export declare function resourceAddition(resource: Pick<Resource, 'fields'>, drift: SchemaDrift): ResourceAddition;
55
- /** The source of a migration that applies `addition` with alterResourceTable. */
56
- export declare function additionMigrationSource(name: string, addition: ResourceAddition): string;
55
+ /**
56
+ * Standard columns the definition expects but the table lacks. alterResourceTable adds
57
+ * field columns only; for the `version` column of `version: true` (#138) the generated
58
+ * migration adds it with a fixed statement (existing rows start at version 1). The other
59
+ * standard columns (org_unit_id, doc_status, ...) carry meaning no default can supply,
60
+ * so they are reported for a hand-written expand migration.
61
+ */
62
+ export declare function missingStandardColumns(drift: SchemaDrift): {
63
+ statements: string[];
64
+ unsupported: string[];
65
+ };
66
+ /**
67
+ * The source of a migration that runs `statements` (from missingStandardColumns), then
68
+ * applies `addition` with alterResourceTable.
69
+ */
70
+ export declare function additionMigrationSource(name: string, addition: ResourceAddition, statements?: readonly string[]): string;
@@ -135,19 +135,52 @@ export function resourceAddition(resource, drift) {
135
135
  ...(recreateUnique.length ? { recreateUnique } : {}),
136
136
  };
137
137
  }
138
- /** The source of a migration that applies `addition` with alterResourceTable. */
139
- export function additionMigrationSource(name, addition) {
138
+ /**
139
+ * Standard columns the definition expects but the table lacks. alterResourceTable adds
140
+ * field columns only; for the `version` column of `version: true` (#138) the generated
141
+ * migration adds it with a fixed statement (existing rows start at version 1). The other
142
+ * standard columns (org_unit_id, doc_status, ...) carry meaning no default can supply,
143
+ * so they are reported for a hand-written expand migration.
144
+ */
145
+ export function missingStandardColumns(drift) {
146
+ const statements = [];
147
+ const unsupported = [];
148
+ for (const column of drift.missingColumns) {
149
+ if (column.field)
150
+ continue;
151
+ if (column.name === 'version')
152
+ statements.push(`ALTER TABLE ${drift.table} ADD COLUMN IF NOT EXISTS version integer NOT NULL DEFAULT 1`);
153
+ else
154
+ unsupported.push(column.name);
155
+ }
156
+ return { statements, unsupported };
157
+ }
158
+ /**
159
+ * The source of a migration that runs `statements` (from missingStandardColumns), then
160
+ * applies `addition` with alterResourceTable.
161
+ */
162
+ export function additionMigrationSource(name, addition, statements = []) {
163
+ const client = statements.length ? 'db' : 'this.db.getWriteClient()';
164
+ const lines = [
165
+ ...(statements.length ? [' const db = this.db.getWriteClient()'] : []),
166
+ ...statements.map((sql) => ` await db.raw(${JSON.stringify(sql)})`),
167
+ ...(Object.keys(addition).length
168
+ ? [
169
+ ` await alterResourceTable(${client}, '${name}', ${JSON.stringify(addition, null, 2)
170
+ .split('\n')
171
+ .join('\n ')})`,
172
+ ]
173
+ : []),
174
+ ];
175
+ const imports = Object.keys(addition).length ? "import { alterResourceTable } from 'adula'\n" : '';
140
176
  return `import { BaseSchema } from '@adonisjs/lucid/schema'
141
- import { alterResourceTable } from 'adula'
142
-
177
+ ${imports}
143
178
  // Generated by \`node ace adula:resource:migration ${name}\`: what the database lacked and
144
179
  // relaxing changes only (NOT NULL dropped, unique indexes no longer counting cancelled documents).
145
180
  // Immutable once it has run; later definition changes get a new migration.
146
181
  export default class extends BaseSchema {
147
182
  async up() {
148
- await alterResourceTable(this.db.getWriteClient(), '${name}', ${JSON.stringify(addition, null, 2)
149
- .split('\n')
150
- .join('\n ')})
183
+ ${lines.join('\n')}
151
184
  }
152
185
  async down() {
153
186
  throw new Error('Use an expand/contract migration or restore a backup')
@@ -224,6 +224,8 @@ function typesSection(document) {
224
224
  ` status: number`,
225
225
  ` statusText: string`,
226
226
  ` text(): Promise<string>`,
227
+ ` /** Needed only for binary downloads such as imports.xlsxTemplate(). */`,
228
+ ` arrayBuffer?(): Promise<ArrayBuffer>`,
227
229
  `}`,
228
230
  `/** The global fetch, or any compatible implementation (tests, proxies, retries). */`,
229
231
  `export type AdulaFetch = (`,
@@ -319,7 +321,7 @@ function typesSection(document) {
319
321
  type: 'object',
320
322
  properties: { mapping: { type: 'object', additionalProperties: { type: 'string' } } },
321
323
  required: ['mapping'],
322
- }, names), `export interface AdulaImportsClient {`, ` /** The caller's latest batches. */`, ` list(): Promise<AdulaImportBatch[]>`, ` /** One batch; after a dry run, report holds each row's outcome. */`, ` show(id: number): Promise<AdulaImportBatch>`, ` /** Uploads a file; the batch then waits for start() with its column mapping. */`, ` create<R extends AdulaImportableResource>(resource: R, input: AdulaImportInputs[R]): Promise<AdulaImportBatch>`, ` /** Queues the batch: dryRun validates only (status validated); start again to import. */`, ` start(id: number, input: AdulaImportStartInput): Promise<AdulaImportBatch>`, ` /** The CSV header row (UTF-8 with BOM) of the fields the caller may import. */`, ` template<R extends AdulaImportableResource>(resource: R, options?: { mode?: AdulaImportModes[R] }): Promise<string>`, `}`);
324
+ }, names), `export interface AdulaImportsClient {`, ` /** The caller's latest batches. */`, ` list(): Promise<AdulaImportBatch[]>`, ` /** One batch; after a dry run, report holds each row's outcome. */`, ` show(id: number): Promise<AdulaImportBatch>`, ` /** Uploads a file; the batch then waits for start() with its column mapping. */`, ` create<R extends AdulaImportableResource>(resource: R, input: AdulaImportInputs[R]): Promise<AdulaImportBatch>`, ` /** Queues the batch: dryRun validates only (status validated); start again to import. */`, ` start(id: number, input: AdulaImportStartInput): Promise<AdulaImportBatch>`, ` /** The CSV header row (UTF-8 with BOM) of the fields the caller may import. */`, ` template<R extends AdulaImportableResource>(resource: R, options?: { mode?: AdulaImportModes[R] }): Promise<string>`, ` /** The same header row as an Excel workbook (.xlsx bytes). */`, ` xlsxTemplate<R extends AdulaImportableResource>(resource: R, options?: { mode?: AdulaImportModes[R] }): Promise<ArrayBuffer>`, `}`);
323
325
  }
324
326
  lines.push(`export interface AdulaClient {`, ` resources: AdulaResourceClients`, ...(imports ? [` imports: AdulaImportsClient`] : []), ` /** Any other API call: the path is relative to basePath; JSON in and out. */`, ` request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>`, `}`);
325
327
  return { text: lines.join('\n'), resources, basePath, imports };
@@ -377,11 +379,15 @@ export function createAdulaClient(options: AdulaClientOptions): AdulaClient {
377
379
  async function call(
378
380
  method: string,
379
381
  path: string,
380
- init: { query?: Record<string, unknown>; body?: unknown; text?: boolean } = {}
382
+ init: { query?: Record<string, unknown>; body?: unknown; text?: boolean; binary?: boolean } = {}
381
383
  ): Promise<unknown> {
382
384
  const headers: Record<string, string> = {
383
385
  Authorization: 'Bearer ' + options.token,
384
- Accept: init.text ? 'text/csv, text/plain, */*' : 'application/json',
386
+ Accept: init.binary
387
+ ? 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/json'
388
+ : init.text
389
+ ? 'text/csv, text/plain, */*'
390
+ : 'application/json',
385
391
  }
386
392
  if (init.body !== undefined) headers['Content-Type'] = 'application/json'
387
393
  const response = await fetcher!(root + path + adulaQuery(init.query), {
@@ -389,6 +395,10 @@ export function createAdulaClient(options: AdulaClientOptions): AdulaClient {
389
395
  headers,
390
396
  ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
391
397
  })
398
+ if (init.binary && response.ok) {
399
+ if (!response.arrayBuffer) throw new Error('The fetch implementation cannot read binary responses')
400
+ return response.arrayBuffer()
401
+ }
392
402
  const raw = await response.text()
393
403
  if (!response.ok) {
394
404
  let parsed: unknown
@@ -453,6 +463,11 @@ export function createAdulaClient(options: AdulaClientOptions): AdulaClient {
453
463
  query: options,
454
464
  text: true,
455
465
  }),
466
+ xlsxTemplate: (resource: string, options?: { mode?: string }) =>
467
+ call('GET', '/resources/' + segment(resource) + '/imports/template', {
468
+ query: { ...options, format: 'xlsx' },
469
+ binary: true,
470
+ }),
456
471
  }
457
472
  return client as unknown as AdulaClient
458
473
  }
@@ -70,7 +70,7 @@ export type ActorSource = {
70
70
  load(id: number): Promise<Actor>;
71
71
  };
72
72
  export type ImportBatchesOptions = {
73
- /** Extra file formats; CSV is always available. See ImportAdapter. */
73
+ /** Extra file formats; CSV and xlsx are always available. See ImportAdapter. */
74
74
  adapters?: ImportAdapter[];
75
75
  };
76
76
  export type ImportCreateInput = {
@@ -110,7 +110,7 @@ export declare class ImportBatches {
110
110
  private formats;
111
111
  constructor(db: Knex, registry: ResourceRegistry, resources: ResourceService, actors: ActorSource, options?: ImportBatchesOptions);
112
112
  /**
113
- * Adds a file format, for example an XLSX adapter. A later adapter with the same
113
+ * Adds a file format, for example an ODS adapter. A later adapter with the same
114
114
  * name replaces the earlier one; CSV stays the fallback for text without an extension.
115
115
  */
116
116
  registerAdapter(adapter: ImportAdapter): this;
@@ -129,6 +129,15 @@ export declare class ImportBatches {
129
129
  fileName: string;
130
130
  content: string;
131
131
  };
132
+ /**
133
+ * The same template as an Excel workbook: one right-to-left sheet whose bold header row
134
+ * holds the actor's importable fields, required ones marked with `*`.
135
+ */
136
+ xlsxTemplate(name: string, actor: Actor, mode?: ImportMode): Promise<{
137
+ fileName: string;
138
+ mimeType: string;
139
+ content: Uint8Array<ArrayBufferLike>;
140
+ }>;
132
141
  create(name: string, actor: Actor, input: ImportCreateInput): Promise<ImportBatchRecord>;
133
142
  show(id: unknown, actor: Actor): Promise<ImportBatchRecord>;
134
143
  list(actor: Actor): Promise<ImportBatchRecord[]>;
@@ -156,8 +165,11 @@ export declare class ImportBatches {
156
165
  } | null>;
157
166
  /**
158
167
  * Saves one row through ResourceService. Upsert first looks for the live record with
159
- * the same match value; ResourceService then authorizes the update against the actor's
160
- * scope and rules and checks the record's current `version`. A real import runs in a
168
+ * the same match value among the records the actor may update (scope and role rules as
169
+ * SQL, as list() applies them); ResourceService then authorizes the update and checks
170
+ * the record's current `version`. A value held only by a record outside that reach takes
171
+ * the create path and answers exactly as a create of it would (a duplicate from the
172
+ * unique index), so the row never tells the importer where the value is stored. A real import runs in a
161
173
  * savepoint of `trx` (the caller's progress transaction); a dry run does the same inside
162
174
  * a transaction that is always rolled back.
163
175
  */
@@ -2,11 +2,15 @@ import { randomUUID } from 'node:crypto';
2
2
  import Papa from 'papaparse';
3
3
  import { subject } from '@casl/ability';
4
4
  import { buildAbility } from '../auth/ability.js';
5
+ import { accessibleBy } from '../auth/sql.js';
5
6
  import { columnName } from '../resource/define_resource.js';
6
7
  import { AdulaError } from '../admin/errors.js';
7
8
  import { notifyWithTemplate } from '../core/message_templates.js';
8
9
  import { translate } from '../languages/catalog.js';
9
10
  import { csvImportAdapter, extensionOf, importFile, } from './import_adapters.js';
11
+ import { XLSX_MIME_TYPE, xlsxImportAdapter } from './xlsx.js';
12
+ import { guardFormula } from '../admin/resource/export.js';
13
+ import writeXlsxFile from 'write-excel-file/node';
10
14
  export const IMPORT_ROW_LIMIT = 5000;
11
15
  const COLUMN_LIMIT = 100;
12
16
  const ERROR_LIMIT = 200;
@@ -108,7 +112,7 @@ export class ImportBatches {
108
112
  registry;
109
113
  resources;
110
114
  actors;
111
- formats = [csvImportAdapter];
115
+ formats = [csvImportAdapter, xlsxImportAdapter];
112
116
  constructor(db, registry, resources, actors, options = {}) {
113
117
  this.db = db;
114
118
  this.registry = registry;
@@ -118,7 +122,7 @@ export class ImportBatches {
118
122
  this.registerAdapter(adapter);
119
123
  }
120
124
  /**
121
- * Adds a file format, for example an XLSX adapter. A later adapter with the same
125
+ * Adds a file format, for example an ODS adapter. A later adapter with the same
122
126
  * name replaces the earlier one; CSV stays the fallback for text without an extension.
123
127
  */
124
128
  registerAdapter(adapter) {
@@ -185,6 +189,26 @@ export class ImportBatches {
185
189
  content: `\uFEFF${Papa.unparse([headers])}\n`,
186
190
  };
187
191
  }
192
+ /**
193
+ * The same template as an Excel workbook: one right-to-left sheet whose bold header row
194
+ * holds the actor's importable fields, required ones marked with `*`.
195
+ */
196
+ async xlsxTemplate(name, actor, mode = 'create') {
197
+ const targets = this.targets(name, actor, mode);
198
+ const header = targets.map((target) => ({
199
+ value: guardFormula(`${target.label}${target.required ? ' *' : ''}`),
200
+ fontWeight: 'bold',
201
+ }));
202
+ const content = await writeXlsxFile([header], {
203
+ rightToLeft: true,
204
+ stickyRowsCount: 1,
205
+ }).toBuffer();
206
+ return {
207
+ fileName: `${name}-template.xlsx`,
208
+ mimeType: XLSX_MIME_TYPE,
209
+ content: new Uint8Array(content.buffer, content.byteOffset, content.byteLength),
210
+ };
211
+ }
188
212
  async create(name, actor, input) {
189
213
  const mode = this.mode(input.mode ?? 'create');
190
214
  const targets = this.targets(name, actor, mode);
@@ -506,8 +530,11 @@ export class ImportBatches {
506
530
  }
507
531
  /**
508
532
  * Saves one row through ResourceService. Upsert first looks for the live record with
509
- * the same match value; ResourceService then authorizes the update against the actor's
510
- * scope and rules and checks the record's current `version`. A real import runs in a
533
+ * the same match value among the records the actor may update (scope and role rules as
534
+ * SQL, as list() applies them); ResourceService then authorizes the update and checks
535
+ * the record's current `version`. A value held only by a record outside that reach takes
536
+ * the create path and answers exactly as a create of it would (a duplicate from the
537
+ * unique index), so the row never tells the importer where the value is stored. A real import runs in a
511
538
  * savepoint of `trx` (the caller's progress transaction); a dry run does the same inside
512
539
  * a transaction that is always rolled back.
513
540
  */
@@ -519,10 +546,11 @@ export class ImportBatches {
519
546
  const value = input[matchField];
520
547
  if (value === null || value === undefined)
521
548
  throw new Error(`${field.label.ar}: قيمة المطابقة مطلوبة`);
522
- const found = await scope(resource.name)
523
- .whereNull('deleted_at')
524
- .where(field.column ?? columnName(matchField), value)
525
- .first(['id', ...(resource.version ? ['version'] : [])]);
549
+ const reachable = scope(`${resource.name} as r`)
550
+ .whereNull('r.deleted_at')
551
+ .where(`r.${field.column ?? columnName(matchField)}`, value);
552
+ accessibleBy(reachable, buildAbility(actor.rules, this.registry.all()), actor, 'update', resource);
553
+ const found = await reachable.first(['r.id', ...(resource.version ? ['r.version'] : [])]);
526
554
  if (found) {
527
555
  id = Number(found.id);
528
556
  if (resource.version)
@@ -606,7 +606,7 @@ export function openApiDocument(registry, options) {
606
606
  },
607
607
  format: {
608
608
  type: 'string',
609
- description: "Import adapter name, for example 'csv' (default: detected)",
609
+ description: "Import adapter name, for example 'csv' or 'xlsx' (default: detected)",
610
610
  },
611
611
  encoding: {
612
612
  enum: ['base64'],
@@ -638,7 +638,7 @@ export function openApiDocument(registry, options) {
638
638
  get: {
639
639
  tags: [tag, 'Imports'],
640
640
  operationId: operationId('importTemplate'),
641
- summary: `CSV template for importing ${tag}`,
641
+ summary: `CSV or Excel template for importing ${tag}`,
642
642
  parameters: [
643
643
  {
644
644
  name: 'mode',
@@ -646,11 +646,22 @@ export function openApiDocument(registry, options) {
646
646
  description: 'upsert also needs update permission',
647
647
  schema: { enum: modes },
648
648
  },
649
+ {
650
+ name: 'format',
651
+ in: 'query',
652
+ description: 'csv (default) or xlsx',
653
+ schema: { enum: ['csv', 'xlsx'] },
654
+ },
649
655
  ],
650
656
  responses: {
651
657
  200: {
652
- description: 'CSV header row',
653
- content: { 'text/csv': { schema: { type: 'string' } } },
658
+ description: 'The header row, as CSV or as an Excel workbook',
659
+ content: {
660
+ 'text/csv': { schema: { type: 'string' } },
661
+ 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': {
662
+ schema: { type: 'string', format: 'binary' },
663
+ },
664
+ },
654
665
  },
655
666
  403: error,
656
667
  },
@@ -28,17 +28,52 @@ export declare class OutboundTargetError extends Error {
28
28
  * NAT64 (64:ff9b::/96) addresses are checked by the IPv4 address they embed.
29
29
  */
30
30
  export declare function isBlockedAddress(address: string): boolean;
31
+ /** True for a link-local address, including IPv4-mapped, IPv4-translated and NAT64 forms. */
32
+ export declare function isLinkLocalAddress(address: string): boolean;
33
+ export declare const defaultResolve: (host: string) => Promise<string[]>;
31
34
  /**
32
35
  * Resolves a URL's host once and returns the address to pin the connection to.
33
36
  * Every resolved address must be public unless private targets are allowed.
34
37
  */
35
38
  export declare function resolveOutboundTarget(url: URL, options?: OutboundOptions): Promise<OutboundTarget>;
39
+ /** A request through the pinned connection; the response body is read up to a bound. */
40
+ export type PinnedRequest = {
41
+ method: string;
42
+ headers: Record<string, string>;
43
+ body?: string | Uint8Array;
44
+ signal: AbortSignal;
45
+ target: OutboundTarget;
46
+ /** Bytes of the response body kept; 0 discards it. A longer body fails the request. */
47
+ maxResponseBytes?: number;
48
+ };
49
+ export type PinnedResponse = {
50
+ status: number;
51
+ headers: Record<string, string | string[] | undefined>;
52
+ body: Buffer;
53
+ };
54
+ /** Raised when a response body exceeds the caller's bound. */
55
+ export declare class OutboundResponseTooLargeError extends Error {
56
+ constructor();
57
+ }
58
+ /**
59
+ * Sends a request whose TCP connection goes to the pinned address; redirects are not
60
+ * followed and the response body is bounded.
61
+ */
62
+ export declare function pinnedRequest(url: URL, init: PinnedRequest): Promise<PinnedResponse>;
36
63
  /** Sends a POST whose TCP connection goes to the pinned address; redirects are not followed. */
37
64
  export declare function pinnedPost(url: URL, init: OutboundRequest & {
38
65
  target: OutboundTarget;
39
66
  }): Promise<{
40
67
  status: number;
41
68
  }>;
69
+ /**
70
+ * Validates an absolute URL for an outbound request: https only (http when private targets
71
+ * are allowed), no credentials, and a resolved address that is public unless allowed.
72
+ */
73
+ export declare function guardOutboundUrl(value: string | URL, options?: OutboundOptions): Promise<{
74
+ url: import("node:url").URL;
75
+ target: OutboundTarget;
76
+ }>;
42
77
  /**
43
78
  * The guarded outbound HTTP client: validates the URL, resolves its host once,
44
79
  * refuses private targets unless allowed and connects to the validated address.
@@ -47,5 +82,13 @@ export declare function pinnedPost(url: URL, init: OutboundRequest & {
47
82
  export declare function createOutboundPoster(options?: OutboundOptions): (value: string, init: OutboundRequest) => Promise<{
48
83
  status: number;
49
84
  }>;
85
+ /**
86
+ * The guarded client for calls that need the response body (an API answer, ADR 052): the
87
+ * same URL, address and redirect rules as createOutboundPoster, through pinnedRequest with
88
+ * the body bounded by `maxResponseBytes` (OutboundResponseTooLargeError above it).
89
+ */
90
+ export declare function createOutboundRequester(options?: OutboundOptions): (value: string, init: OutboundRequest & {
91
+ maxResponseBytes: number;
92
+ }) => Promise<PinnedResponse>;
50
93
  /** Maps a delivery failure to a stored category without keeping its message. */
51
94
  export declare function outboundErrorCategory(error: unknown): OutboundErrorCategory;