agentlang 0.10.9 → 0.11.0

package/src/runtime/modules/auth.ts

@@ -27,6 +27,7 @@ import {
   set_getUserTenantId,
   PathAttributeName,
 } from '../defs.js';
+import { createCodedError } from '../errors/coded-error.js';
 import {
   DbContext,
   getManyByRawQuery,
@@ -1045,7 +1046,7 @@ function fetchAuthImpl(): AgentlangAuth {
   if (runtimeAuth) {
     return runtimeAuth;
   } else {
-    throw new Error('Auth not initialized');
+    throw createCodedError('Auth not initialized', 'AL_AUTH_NOT_INITIALIZED');
   }
 }
 
@@ -1115,7 +1116,9 @@ export async function forgotPasswordUser(username: string, env: Environment): Pr
     const email = username.toLowerCase();
     const allowed = await fetchAuthImpl().userExistsInIdentityProvider(email, env);
     if (!allowed) {
-      throw new UserNotFoundError('Email not registered');
+      throw new UserNotFoundError('Email not registered', {
+        agentlangCode: 'AL_AUTH_EMAIL_NOT_REGISTERED',
+      });
     }
     await fetchAuthImpl().forgotPassword(email, env);
     return { status: 'ok', message: 'Password reset code sent' };
@@ -1265,7 +1268,9 @@ export async function changePassword(
       return undefined;
     }
   } else {
-    throw new UnauthorisedError(`No active session for user ${user}`);
+    throw new UnauthorisedError(`No active session for user ${user}`, {
+      agentlangCode: 'AL_AUTH_NO_ACTIVE_SESSION_CHANGE_PW',
+    });
   }
 }
 
@@ -1292,7 +1297,9 @@ async function verifyJwtToken(token: string, env?: Environment): Promise<ActiveS
     try {
       // Validate JWT structure first
       if (!isJwtToken(token)) {
-        throw new UnauthorisedError('Invalid JWT token structure');
+        throw new UnauthorisedError('Invalid JWT token structure', {
+          agentlangCode: 'AL_AUTH_JWT_STRUCTURE_INVALID',
+        });
       }
 
       // Verify the JWT token directly with Cognito
@@ -1307,7 +1314,9 @@ async function verifyJwtToken(token: string, env?: Environment): Promise<ActiveS
       const email = payload.email || payload['cognito:username'];
 
       if (!userId) {
-        throw new UnauthorisedError('Invalid JWT token: missing user identifier');
+        throw new UnauthorisedError('Invalid JWT token: missing user identifier', {
+          agentlangCode: 'AL_AUTH_JWT_MISSING_USER_ID',
+        });
       }
 
       let localUser = null;
@@ -1323,7 +1332,9 @@ async function verifyJwtToken(token: string, env?: Environment): Promise<ActiveS
         logger.warn(
           `User not found in local database for JWT token. Email: ${email}, UserId: ${userId}`
         );
-        throw new UnauthorisedError(`User not found in local database`);
+        throw new UnauthorisedError(`User not found in local database`, {
+          agentlangCode: 'AL_AUTH_JWT_USER_NOT_IN_DB',
+        });
       }
 
       // Use the local user's ID for consistency
@@ -1332,12 +1343,16 @@ async function verifyJwtToken(token: string, env?: Environment): Promise<ActiveS
       // Check if user status is 'Active'
       const userStatus = localUser.lookup('status');
       if (userStatus !== 'Active') {
-        throw new UnauthorisedError(`User account is not active. Status: ${userStatus}`);
+        throw new UnauthorisedError(`User account is not active. Status: ${userStatus}`, {
+          agentlangCode: 'AL_AUTH_USER_NOT_ACTIVE_JWT',
+        });
       }
 
       const sess = await findUserSession(localUserId, env);
       if (!sess) {
-        throw new UnauthorisedError(`No session found for user ${email}, UserId: ${userId}`);
+        throw new UnauthorisedError(`No session found for user ${email}, UserId: ${userId}`, {
+          agentlangCode: 'AL_AUTH_NO_SESSION_JWT',
+        });
       }
       // For JWT tokens, we use the token itself as sessionId for tracking
       return { sessionId: sess.lookup('id'), userId: localUserId };
@@ -1349,7 +1364,9 @@ async function verifyJwtToken(token: string, env?: Environment): Promise<ActiveS
         errorName: err.name,
         errorMessage: err.message,
       });
-      throw new UnauthorisedError('JWT token verification failed');
+      throw new UnauthorisedError('JWT token verification failed', {
+        agentlangCode: 'AL_AUTH_JWT_VERIFY_WRAPPER',
+      });
     }
   };
   if (needCommit) {
@@ -1372,7 +1389,9 @@ async function verifySessionToken(token: string, env?: Environment): Promise<Act
       if (user) {
         const userStatus = user.lookup('status');
         if (userStatus !== 'Active') {
-          throw new UnauthorisedError(`User account is not active. Status: ${userStatus}`);
+          throw new UnauthorisedError(`User account is not active. Status: ${userStatus}`, {
+            agentlangCode: 'AL_AUTH_USER_NOT_ACTIVE_SESSION',
+          });
         }
       }
 
@@ -1382,7 +1401,9 @@ async function verifySessionToken(token: string, env?: Environment): Promise<Act
         return { sessionId: sessId, userId: userId };
       } else {
         logger.warn(`No active session found for user '${userId}'`);
-        throw new UnauthorisedError(`No active session for user '${userId}'`);
+        throw new UnauthorisedError(`No active session for user '${userId}'`, {
+          agentlangCode: 'AL_AUTH_NO_ACTIVE_SESSION_TOKEN',
+        });
       }
     } catch (err: any) {
       if (err instanceof UnauthorisedError) {
@@ -1394,7 +1415,9 @@ async function verifySessionToken(token: string, env?: Environment): Promise<Act
         errorMessage: err.message,
         sessionId: sessId,
       });
-      throw new UnauthorisedError('Session verification failed');
+      throw new UnauthorisedError('Session verification failed', {
+        agentlangCode: 'AL_AUTH_SESSION_VERIFY_WRAPPER',
+      });
     }
   };
   if (needCommit) {

package/src/runtime/modules/core.ts

@@ -167,6 +167,16 @@ entity Migration {
   downs String @optional
 }
 
+// Custom HTTP error messages. \`target\` is "*" for a universal (code-only) override,
+// or "module/Entry" for an entity-specific one. \`message\` may contain the
+// {{code}} and {{message}} placeholders, substituted at resolution time.
+entity errorMessage {
+  id UUID @id @default(uuid()),
+  target String @default("*") @indexed,
+  code String @indexed,
+  message String
+}
+
 @public event Query {
   q Any
 }
@@ -283,6 +293,22 @@ export async function lookupTimersWithRunningStatus(): Promise<Instance[]> {
   return await parseAndEvaluateStatement(`{agentlang/timer {status? "R"}}`);
 }
 
+/**
+ * Look up a custom error-message template stored in the `agentlang/errorMessage`
+ * system entity. `target` is "*" for a universal override or "module/Entry" for an
+ * entity-specific one. Returns the stored `message`, or undefined when none exists.
+ */
+export async function lookupCustomErrorMessage(
+  target: string,
+  code: string
+): Promise<string | undefined> {
+  const r: any = await parseAndEvaluateStatement(
+    `{${DefaultModuleName}/errorMessage {target? "${escapeSpecialChars(target)}", code? "${escapeSpecialChars(code)}"}}`
+  );
+  const insts: Instance[] = Array.isArray(r) ? r : r ? [r] : [];
+  return insts.length > 0 ? insts[0].lookup('message') : undefined;
+}
+
 async function addAudit(
   env: Environment,
   action: 'c' | 'd' | 'u',

package/src/runtime/resolvers/sqldb/database.ts

@@ -45,6 +45,8 @@ import {
   TenantAttributeName,
   UnauthorisedError,
 } from '../../defs.js';
+import { createCodedError } from '../../errors/coded-error.js';
+import { mapDatabaseError } from './db-errors.js';
 import { saveMigration } from '../../modules/core.js';
 import { getAppSpec } from '../../loader.js';
 import { WhereClause } from '../interface.js';
@@ -393,9 +395,10 @@ async function validateSchemaInProd(dataSource: DataSource) {
   );
   if (pendingQueries.length > 0) {
     const pending = pendingQueries.join('\n  ');
-    throw new Error(
+    throw createCodedError(
       `Schema mismatch detected: the app model does not match the database schema. ` +
-        `Run migrations before starting in production mode.\n  Pending changes:\n  ${pending}`
+        `Run migrations before starting in production mode.\n  Pending changes:\n  ${pending}`,
+      'AL_DB_SCHEMA_MISMATCH_PROD'
     );
   }
 }
@@ -431,8 +434,9 @@ async function maybeHandleMigrations(dataSource: DataSource) {
       const simulation = await simulateMigration(dataSource);
       if (!simulation.success) {
         logger.error(`Migration simulation failed:\n  ${simulation.errors.join('\n  ')}`);
-        throw new Error(
-          `Migration aborted: simulation failed.\n  ${simulation.errors.join('\n  ')}`
+        throw createCodedError(
+          `Migration aborted: simulation failed.\n  ${simulation.errors.join('\n  ')}`,
+          'AL_DB_MIGRATION_SIMULATION_FAILED'
         );
       }
       logger.info('Migration simulation passed.');
@@ -443,8 +447,9 @@ async function maybeHandleMigrations(dataSource: DataSource) {
       const simulation = await simulateMigration(dataSource);
       if (!simulation.success) {
         logger.error(`Migration simulation failed:\n  ${simulation.errors.join('\n  ')}`);
-        throw new Error(
-          `Migration aborted: simulation failed.\n  ${simulation.errors.join('\n  ')}`
+        throw createCodedError(
+          `Migration aborted: simulation failed.\n  ${simulation.errors.join('\n  ')}`,
+          'AL_DB_MIGRATION_SIMULATION_FAILED'
         );
       }
       logger.info('Migration simulation passed, applying changes...');
@@ -530,7 +535,10 @@ function getDsFunction(
     case 'sqljs':
       return makeSqljsDataSource;
     default:
-      throw new Error(`Unsupported database type - ${config?.type}`);
+      throw createCodedError(
+        `Unsupported database type - ${config?.type}`,
+        'AL_DB_UNSUPPORTED_TYPE'
+      );
   }
 }
 
@@ -595,7 +603,10 @@ export async function initDatabase(config: DatabaseConfig | undefined) {
         await initVectorStore(vectEnts, DbContext.getGlobalContext());
       }
     } else {
-      throw new Error(`Unsupported database type - ${getDbType(AppConfig?.store)}`);
+      throw createCodedError(
+        `Unsupported database type - ${getDbType(AppConfig?.store)}`,
+        'AL_DB_UNSUPPORTED_TYPE_INIT'
+      );
     }
   }
 }
@@ -617,9 +628,13 @@ async function insertRowsHelper(
   ctx: DbContext,
   doUpsert: boolean
 ): Promise<void> {
-  const repo = getDatasourceForTransaction(ctx.txnId).getRepository(tableName);
-  if (doUpsert) await repo.save(rows);
-  else await repo.insert(rows);
+  try {
+    const repo = getDatasourceForTransaction(ctx.txnId).getRepository(tableName);
+    if (doUpsert) await repo.save(rows);
+    else await repo.insert(rows);
+  } catch (err) {
+    mapDatabaseError(err);
+  }
 }
 
 export async function addRowForFullTextSearch(
@@ -884,7 +899,10 @@ export async function insertRows(
       }
     }
   } else {
-    throw new UnauthorisedError({ opr: 'insert', entity: tableName });
+    throw new UnauthorisedError(
+      { opr: 'insert', entity: tableName },
+      { agentlangCode: 'AL_DB_INSERT_UNAUTHORIZED' }
+    );
   }
 }
 
@@ -926,7 +944,10 @@ export async function insertBetweenRow(
     const row = Object.fromEntries(attrs);
     await insertRow(n, row, ctx.clone().setNeedAuthCheck(false), false);
   } else {
-    throw new UnauthorisedError({ opr: 'insert', entity: n });
+    throw new UnauthorisedError(
+      { opr: 'insert', entity: n },
+      { agentlangCode: 'AL_DB_BETWEEN_INSERT_UNAUTHORIZED' }
+    );
   }
 }
 
@@ -1046,12 +1067,16 @@ export async function updateRow(
   updateObj: object,
   ctx: DbContext
 ): Promise<boolean> {
-  await getDatasourceForTransaction(ctx.txnId)
-    .createQueryBuilder()
-    .update(tableName)
-    .set(updateObj)
-    .where(objectToWhereClause(queryObj, queryVals), queryVals)
-    .execute();
+  try {
+    await getDatasourceForTransaction(ctx.txnId)
+      .createQueryBuilder()
+      .update(tableName)
+      .set(updateObj)
+      .where(objectToWhereClause(queryObj, queryVals), queryVals)
+      .execute();
+  } catch (err) {
+    mapDatabaseError(err);
+  }
   return true;
 }
 
@@ -1069,12 +1094,16 @@ function queryObjectAsWhereClause(qobj: QueryObject): string {
 
 export async function hardDeleteRow(tableName: string, queryObject: QueryObject, ctx: DbContext) {
   const clause = queryObjectAsWhereClause(queryObject);
-  await getDatasourceForTransaction(ctx.txnId)
-    .createQueryBuilder()
-    .delete()
-    .from(tableName)
-    .where(clause, Object.fromEntries(queryObject))
-    .execute();
+  try {
+    await getDatasourceForTransaction(ctx.txnId)
+      .createQueryBuilder()
+      .delete()
+      .from(tableName)
+      .where(clause, Object.fromEntries(queryObject))
+      .execute();
+  } catch (err) {
+    mapDatabaseError(err);
+  }
   return true;
 }
 
@@ -1090,7 +1119,7 @@ function mkBetweenClause(tableName: string | undefined, k: string, queryVals: an
     delete queryVals[k];
     return s;
   } else {
-    throw new Error(`between requires an array argument, not ${ov}`);
+    throw createCodedError(`between requires an array argument, not ${ov}`, 'AL_DB_BETWEEN_ARRAY');
   }
 }
 
@@ -1112,7 +1141,10 @@ function objectToWhereClause(queryObj: object, queryVals: any, tableName?: strin
       } else if (op === '<>' || op === '!=') {
         op = 'IS NOT';
       } else {
-        throw new Error(`Operator ${op} cannot be appplied to SQL NULL`);
+        throw createCodedError(
+          `Operator ${op} cannot be appplied to SQL NULL`,
+          'AL_DB_NULL_OPERATOR'
+        );
       }
     }
     const v = isnullcheck ? 'NULL' : `:${k}`;
@@ -1143,7 +1175,10 @@ function objectToRawWhereClause(queryObj: object, queryVals: any, tableName?: st
       } else if (op === '<>' || op === '!=') {
         op = 'IS NOT';
       } else {
-        throw new Error(`Operator ${op} cannot be appplied to SQL NULL`);
+        throw createCodedError(
+          `Operator ${op} cannot be appplied to SQL NULL`,
+          'AL_DB_NULL_OPERATOR'
+        );
       }
     }
     let clause = '';
@@ -1274,8 +1309,12 @@ export async function getMany(
     qb.skip(querySpec.offset);
   }
   qb.where(queryStr, querySpec.queryVals);
-  if (hasAggregates) return await qb.getRawMany();
-  else return await qb.getMany();
+  try {
+    if (hasAggregates) return await qb.getRawMany();
+    else return await qb.getMany();
+  } catch (err) {
+    mapDatabaseError(err);
+  }
 }
 
 export async function getManyByRawQuery(
@@ -1287,7 +1326,11 @@ export async function getManyByRawQuery(
     .getRepository(tableName)
     .createQueryBuilder();
   qb.where('', querySpec.queryVals);
-  return await qb.getMany();
+  try {
+    return await qb.getMany();
+  } catch (err) {
+    mapDatabaseError(err);
+  }
 }
 
 export async function getManyByJoin(
@@ -1348,7 +1391,7 @@ export async function getManyByJoin(
     }
   });
   if (querySpec.intoSpec === undefined) {
-    throw new Error('SELECT-INTO pattern is missing');
+    throw createCodedError('SELECT-INTO pattern is missing', 'AL_DB_SELECT_INTO_MISSING');
   }
   const intos = querySpec.intoSpec.size > 0 ? intoSpecToSql(querySpec.intoSpec) : '';
   const intos_sep = intos.length === 0 ? '' : ',';
@@ -1370,7 +1413,11 @@ export async function getManyByJoin(
   }
   logger.debug(`Join Query: ${sql}`);
   const qb = getDatasourceForTransaction(ctx.txnId).getRepository(tableName).manager;
-  return await qb.query(sql);
+  try {
+    return await qb.query(sql);
+  } catch (err) {
+    mapDatabaseError(err);
+  }
 }
 
 function intoSpecToSql(intoSpec: Map<string, string>): string {
@@ -1440,7 +1487,11 @@ export async function getAllConnected(
       connAlias,
       buildQueryFromConnnectionInfo(connAlias, alias, connInfo)
     );
-  return await qb.getRawMany();
+  try {
+    return await qb.getRawMany();
+  } catch (err) {
+    mapDatabaseError(err);
+  }
 }
 
 const transactionsDb: Map<string, QueryRunner> = new Map<string, QueryRunner>();
@@ -1453,7 +1504,7 @@ export async function startDbTransaction(): Promise<string> {
     transactionsDb.set(txnId, queryRunner);
     return txnId;
   } else {
-    throw new Error('Database not initialized');
+    throw createCodedError('Database not initialized', 'AL_DB_NOT_INITIALIZED');
   }
 }
 
@@ -1461,13 +1512,13 @@ function getDatasourceForTransaction(txnId: string | undefined): DataSource | En
   if (txnId) {
     const qr: QueryRunner | undefined = transactionsDb.get(txnId);
     if (qr === undefined) {
-      throw new Error(`Transaction not found - ${txnId}`);
+      throw createCodedError(`Transaction not found - ${txnId}`, 'AL_DB_TXN_NOT_FOUND');
     } else {
       return qr.manager;
     }
   } else {
     if (defaultDataSource !== undefined) return defaultDataSource;
-    else throw new Error('No default datasource is initialized');
+    else throw createCodedError('No default datasource is initialized', 'AL_DB_NO_DATASOURCE');
   }
 }
 

package/src/runtime/resolvers/sqldb/db-errors.ts

@@ -0,0 +1,113 @@
+import { QueryFailedError } from 'typeorm';
+import { createCodedError, isCodedError } from '../../errors/coded-error.js';
+
+/**
+ * Normalize TypeORM / driver failures into stable Agentlang codes for HTTP and logging.
+ * Preserves the original message text on the thrown Error.
+ */
+export function mapDatabaseError(err: unknown): never {
+  if (isCodedError(err)) {
+    throw err;
+  }
+
+  const anyErr = err as any;
+  const msg = anyErr instanceof Error ? anyErr.message : String(err);
+  const driver = anyErr?.driverError ?? anyErr;
+  const sqlState =
+    driver?.code !== undefined && driver?.code !== null
+      ? String(driver.code)
+      : anyErr?.code !== undefined && anyErr?.code !== null
+        ? String(anyErr.code)
+        : undefined;
+  const errno = driver?.errno ?? anyErr?.errno;
+
+  // PostgreSQL (SQLSTATE)
+  if (sqlState === '23505') {
+    throw createCodedError(msg, 'AL_DB_UNIQUE_VIOLATION');
+  }
+  if (sqlState === '23503') {
+    throw createCodedError(msg, 'AL_DB_FOREIGN_KEY_VIOLATION');
+  }
+  if (sqlState === '23502') {
+    throw createCodedError(msg, 'AL_DB_NOT_NULL_VIOLATION');
+  }
+  if (sqlState === '23514') {
+    throw createCodedError(msg, 'AL_DB_CHECK_VIOLATION');
+  }
+  // Invalid text representation / datetime / numeric range (e.g. non-UUID passed to a UUID column).
+  if (sqlState === '22P02' || sqlState === '22007' || sqlState === '22003') {
+    throw createCodedError(msg, 'AL_DB_INVALID_TYPE');
+  }
+  if (sqlState === '40P01') {
+    throw createCodedError(msg, 'AL_DB_DEADLOCK');
+  }
+  if (sqlState === '40001' || sqlState === '25P02') {
+    throw createCodedError(msg, 'AL_DB_SERIALIZATION_FAILURE');
+  }
+
+  // MySQL / MariaDB (errno)
+  if (errno === 1062) {
+    throw createCodedError(msg, 'AL_DB_UNIQUE_VIOLATION');
+  }
+  if (errno === 1451 || errno === 1452) {
+    throw createCodedError(msg, 'AL_DB_FOREIGN_KEY_VIOLATION');
+  }
+  if (errno === 1048) {
+    throw createCodedError(msg, 'AL_DB_NOT_NULL_VIOLATION');
+  }
+  if (errno === 1213) {
+    throw createCodedError(msg, 'AL_DB_DEADLOCK');
+  }
+  if (errno === 1205) {
+    throw createCodedError(msg, 'AL_DB_LOCK_WAIT_TIMEOUT');
+  }
+  if (errno === 1366 || errno === 1292) {
+    throw createCodedError(msg, 'AL_DB_INVALID_TYPE');
+  }
+
+  const m = msg.toLowerCase();
+
+  // Cross-driver message heuristics (SQLite, sql.js, edge cases)
+  if (
+    /unique constraint|duplicate key value|duplicate entry|unique failed|constraint failed.*unique/i.test(
+      m
+    )
+  ) {
+    throw createCodedError(msg, 'AL_DB_UNIQUE_VIOLATION');
+  }
+  if (/foreign key constraint|foreign key mismatch|references.*fails/i.test(m)) {
+    throw createCodedError(msg, 'AL_DB_FOREIGN_KEY_VIOLATION');
+  }
+  if (/not-null constraint|null value in column|cannot be null|not null constraint/i.test(m)) {
+    throw createCodedError(msg, 'AL_DB_NOT_NULL_VIOLATION');
+  }
+  if (/check constraint/i.test(m)) {
+    throw createCodedError(msg, 'AL_DB_CHECK_VIOLATION');
+  }
+  if (/deadlock/i.test(m)) {
+    throw createCodedError(msg, 'AL_DB_DEADLOCK');
+  }
+  if (/lock wait timeout|could not obtain lock/i.test(m)) {
+    throw createCodedError(msg, 'AL_DB_LOCK_WAIT_TIMEOUT');
+  }
+  if (/could not serialize|serialization failure/i.test(m)) {
+    throw createCodedError(msg, 'AL_DB_SERIALIZATION_FAILURE');
+  }
+  if (/invalid input syntax|incorrect .* value|out of range|datatype mismatch/i.test(m)) {
+    throw createCodedError(msg, 'AL_DB_INVALID_TYPE');
+  }
+
+  if (anyErr instanceof QueryFailedError && /syntax error|parse error/i.test(m)) {
+    throw createCodedError(msg, 'AL_DB_SYNTAX_ERROR');
+  }
+
+  if (anyErr instanceof QueryFailedError) {
+    throw createCodedError(msg, 'AL_DB_QUERY_FAILED');
+  }
+
+  if (anyErr instanceof Error) {
+    throw createCodedError(msg, 'AL_DB_QUERY_FAILED');
+  }
+
+  throw createCodedError(String(err), 'AL_DB_QUERY_FAILED');
+}

package/src/runtime/state.ts

@@ -140,6 +140,13 @@ export const ConfigSchema = z.object({
       })
     )
     .optional(),
+  customErrorMessages: z
+    .object({
+      // When true, error responses are resolved against the `agentlang/errorMessage`
+      // system entity before falling back to the default message.
+      enabled: z.boolean().default(false),
+    })
+    .optional(),
 });
 
 export type Config = z.infer<typeof ConfigSchema>;

package/src/xlsx.d.ts

@@ -0,0 +1,17 @@
+declare module 'xlsx' {
+  interface WorkSheet {}
+  interface WorkBook {
+    SheetNames: string[];
+    Sheets: { [name: string]: WorkSheet };
+  }
+  export const utils: {
+    book_new(): WorkBook;
+    json_to_sheet<T extends object>(data: T[]): WorkSheet;
+    aoa_to_sheet(data: unknown[][]): WorkSheet;
+    book_append_sheet(workbook: WorkBook, sheet: WorkSheet, name: string): void;
+  };
+  export function write(
+    workbook: WorkBook,
+    opts: { type: 'buffer'; bookType: 'xlsx' | 'csv' }
+  ): Buffer;
+}