ztechno_core 0.0.131 → 0.0.133

package/lib/mollie/index.d.ts

@@ -1,5 +1,8 @@
 export { MollieService } from './services/mollie_service';
 export { CustomerService } from './services/customer_service';
 export { InvoiceService } from './services/invoice_service';
+export { InvoiceAuditService } from './services/invoice_audit_service';
 export { SubscriptionService } from './services/subscription_service';
+export { InvoiceStatusLogOrm } from './orm/invoice_status_log_orm';
+export { PaymentStatusLogOrm } from './orm/payment_status_log_orm';
 export * from './types/mollie_types';

package/lib/mollie/index.js

@@ -26,7 +26,14 @@ var __exportStar =
       if (p !== 'default' && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
   };
 Object.defineProperty(exports, '__esModule', { value: true });
-exports.SubscriptionService = exports.InvoiceService = exports.CustomerService = exports.MollieService = void 0;
+exports.PaymentStatusLogOrm =
+  exports.InvoiceStatusLogOrm =
+  exports.SubscriptionService =
+  exports.InvoiceAuditService =
+  exports.InvoiceService =
+  exports.CustomerService =
+  exports.MollieService =
+    void 0;
 // Services
 var mollie_service_1 = require('./services/mollie_service');
 Object.defineProperty(exports, 'MollieService', {
@@ -49,6 +56,13 @@ Object.defineProperty(exports, 'InvoiceService', {
     return invoice_service_1.InvoiceService;
   },
 });
+var invoice_audit_service_1 = require('./services/invoice_audit_service');
+Object.defineProperty(exports, 'InvoiceAuditService', {
+  enumerable: true,
+  get: function () {
+    return invoice_audit_service_1.InvoiceAuditService;
+  },
+});
 var subscription_service_1 = require('./services/subscription_service');
 Object.defineProperty(exports, 'SubscriptionService', {
   enumerable: true,
@@ -56,6 +70,21 @@ Object.defineProperty(exports, 'SubscriptionService', {
     return subscription_service_1.SubscriptionService;
   },
 });
+// ORMs (audit log)
+var invoice_status_log_orm_1 = require('./orm/invoice_status_log_orm');
+Object.defineProperty(exports, 'InvoiceStatusLogOrm', {
+  enumerable: true,
+  get: function () {
+    return invoice_status_log_orm_1.InvoiceStatusLogOrm;
+  },
+});
+var payment_status_log_orm_1 = require('./orm/payment_status_log_orm');
+Object.defineProperty(exports, 'PaymentStatusLogOrm', {
+  enumerable: true,
+  get: function () {
+    return payment_status_log_orm_1.PaymentStatusLogOrm;
+  },
+});
 // Public types (entities, inputs, outputs)
 __exportStar(require('./types/mollie_types'), exports);
 // internal_types.ts is intentionally NOT exported —

package/lib/mollie/orm/invoice_payments_orm.d.ts

@@ -1,9 +1,18 @@
 import { ZOrm } from '../../core/orm/orm';
 import { ZSQLService } from '../../core/sql_service';
-import { ZInvoicePayment } from '../types/mollie_types';
+import { ZInvoicePayment, ZAuditActorType } from '../types/mollie_types';
+import { PaymentStatusLogOrm } from './payment_status_log_orm';
 export declare class InvoicePaymentsOrm extends ZOrm {
-  constructor(opt: { sqlService: ZSQLService; alias?: string });
-  upsert(payment: Omit<ZInvoicePayment, 'id' | 'created_at' | 'updated_at'>): Promise<void>;
+  private paymentLogOrm?;
+  constructor(opt: { sqlService: ZSQLService; alias?: string; paymentLogOrm?: PaymentStatusLogOrm });
+  setPaymentLogOrm(orm: PaymentStatusLogOrm): void;
+  upsert(
+    payment: Omit<ZInvoicePayment, 'id' | 'created_at' | 'updated_at'>,
+    audit?: {
+      actorType?: ZAuditActorType;
+      note?: string;
+    },
+  ): Promise<void>;
   findByPaymentId(mollie_payment_id: string): Promise<ZInvoicePayment>;
   findByInvoice(invoice_id: number): Promise<ZInvoicePayment[]>;
   createTable(): Promise<void>;

package/lib/mollie/orm/invoice_payments_orm.js

@@ -5,8 +5,19 @@ const orm_1 = require('../../core/orm/orm');
 class InvoicePaymentsOrm extends orm_1.ZOrm {
   constructor(opt) {
     super({ sqlService: opt.sqlService, alias: opt.alias ?? 'mollie_invoice_payments' });
+    this.paymentLogOrm = opt.paymentLogOrm;
   }
-  async upsert(payment) {
+  setPaymentLogOrm(orm) {
+    this.paymentLogOrm = orm;
+  }
+  async upsert(payment, audit) {
+    // Capture previous status for audit logging
+    let previousStatus = null;
+    let existingPayment;
+    if (this.paymentLogOrm) {
+      existingPayment = await this.findByPaymentId(payment.mollie_payment_id);
+      previousStatus = existingPayment?.status ?? null;
+    }
     await this.sqlService.query(
       /*SQL*/ `
       INSERT INTO \`${this.alias}\`
@@ -28,6 +39,25 @@ class InvoicePaymentsOrm extends orm_1.ZOrm {
     `,
       payment,
     );
+    // Audit log: record status change (or initial insert)
+    if (this.paymentLogOrm) {
+      const newStatus = payment.status;
+      if (previousStatus !== newStatus) {
+        // Fetch the persisted record to get its id
+        const persisted = existingPayment ?? (await this.findByPaymentId(payment.mollie_payment_id));
+        if (persisted) {
+          await this.paymentLogOrm.insert({
+            payment_id: persisted.id,
+            invoice_id: payment.invoice_id,
+            mollie_payment_id: payment.mollie_payment_id,
+            from_status: previousStatus,
+            to_status: newStatus,
+            actor_type: audit?.actorType ?? 'system',
+            note: audit?.note ?? null,
+          });
+        }
+      }
+    }
   }
   async findByPaymentId(mollie_payment_id) {
     const res = await this.sqlService.exec({

package/lib/mollie/orm/invoice_status_log_orm.d.ts

@@ -0,0 +1,9 @@
+import { ZOrm } from '../../core/orm/orm';
+import { ZSQLService } from '../../core/sql_service';
+import { ZInvoiceStatusLogEntry } from '../types/mollie_types';
+export declare class InvoiceStatusLogOrm extends ZOrm {
+  constructor(opt: { sqlService: ZSQLService; alias?: string });
+  insert(entry: Omit<ZInvoiceStatusLogEntry, 'id' | 'created_at'>): Promise<void>;
+  findByInvoiceId(invoiceId: number): Promise<ZInvoiceStatusLogEntry[]>;
+  createTable(): Promise<void>;
+}

package/lib/mollie/orm/invoice_status_log_orm.js

@@ -0,0 +1,52 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.InvoiceStatusLogOrm = void 0;
+const orm_1 = require('../../core/orm/orm');
+class InvoiceStatusLogOrm extends orm_1.ZOrm {
+  constructor(opt) {
+    super({ sqlService: opt.sqlService, alias: opt.alias ?? 'mollie_invoice_status_log' });
+  }
+  async insert(entry) {
+    await this.sqlService.query(
+      /*SQL*/ `
+      INSERT INTO \`${this.alias}\`
+        (invoice_id, from_status, to_status, actor_type, mollie_payment_id, note, metadata)
+      VALUES
+        (:invoice_id, :from_status, :to_status, :actor_type, :mollie_payment_id, :note, :metadata)
+    `,
+      {
+        invoice_id: entry.invoice_id,
+        from_status: entry.from_status ?? null,
+        to_status: entry.to_status,
+        actor_type: entry.actor_type,
+        mollie_payment_id: entry.mollie_payment_id ?? null,
+        note: entry.note ?? null,
+        metadata: entry.metadata != null ? JSON.stringify(entry.metadata) : null,
+      },
+    );
+  }
+  async findByInvoiceId(invoiceId) {
+    return await this.sqlService.exec({
+      query: `SELECT * FROM \`${this.alias}\` WHERE invoice_id=:invoiceId ORDER BY created_at ASC, id ASC`,
+      params: { invoiceId },
+    });
+  }
+  async createTable() {
+    await this.sqlService.query(/*SQL*/ `
+      CREATE TABLE IF NOT EXISTS \`${this.alias}\` (
+        id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+        invoice_id BIGINT UNSIGNED NOT NULL,
+        from_status ENUM('draft','pending','paid','failed','canceled','expired','refunded') NULL,
+        to_status ENUM('draft','pending','paid','failed','canceled','expired','refunded') NOT NULL,
+        actor_type ENUM('webhook','system','admin') NOT NULL,
+        mollie_payment_id VARCHAR(64) NULL,
+        note VARCHAR(512) NULL,
+        metadata JSON NULL,
+        created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        KEY idx_inv_status_log_invoice (invoice_id),
+        KEY idx_inv_status_log_invoice_time (invoice_id, created_at)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
+    `);
+  }
+}
+exports.InvoiceStatusLogOrm = InvoiceStatusLogOrm;

package/lib/mollie/orm/invoices_orm.d.ts

@@ -1,8 +1,11 @@
 import { ZOrm } from '../../core/orm/orm';
 import { ZSQLService } from '../../core/sql_service';
-import { ZInvoice, ZInvoiceStatus } from '../types/mollie_types';
+import { ZInvoice, ZInvoiceStatus, ZAuditContext } from '../types/mollie_types';
+import { InvoiceStatusLogOrm } from './invoice_status_log_orm';
 export declare class InvoicesOrm extends ZOrm {
-  constructor(opt: { sqlService: ZSQLService; alias?: string });
+  private statusLogOrm?;
+  constructor(opt: { sqlService: ZSQLService; alias?: string; statusLogOrm?: InvoiceStatusLogOrm });
+  setStatusLogOrm(orm: InvoiceStatusLogOrm): void;
   create(invoice: Omit<ZInvoice, 'id' | 'created_at' | 'updated_at'>): Promise<{
     insertId: number;
     affectedRows: number;
@@ -13,9 +16,20 @@ export declare class InvoicesOrm extends ZOrm {
   findByPayTokenHash(pay_token_hash: string): Promise<ZInvoice>;
   findAll(): Promise<ZInvoice[]>;
   findLastByYear(year: number): Promise<ZInvoice | undefined>;
-  updateStatus(id: number, status: ZInvoiceStatus, amount_paid?: number, paid_at?: string | null): Promise<void>;
+  updateStatus(
+    id: number,
+    status: ZInvoiceStatus,
+    amount_paid?: number,
+    paid_at?: string | null,
+    audit?: ZAuditContext,
+  ): Promise<void>;
   /** Transitions status only if the current DB status matches `fromStatus`. Safe against concurrent updates. */
-  updateStatusConditional(id: number, status: ZInvoiceStatus, fromStatus: ZInvoiceStatus): Promise<void>;
+  updateStatusConditional(
+    id: number,
+    status: ZInvoiceStatus,
+    fromStatus: ZInvoiceStatus,
+    audit?: Omit<ZAuditContext, 'fromStatus'>,
+  ): Promise<boolean>;
   updatePaymentRef(
     id: number,
     payload: {
@@ -40,6 +54,9 @@ export declare class InvoicesOrm extends ZOrm {
   ): Promise<void>;
   finalizePayToken(id: number): Promise<void>;
   incrementTimesSent(id: number): Promise<void>;
+  setArchivedAt(id: number): Promise<void>;
+  clearArchivedAt(id: number): Promise<void>;
+  isArchived(invoice: ZInvoice): boolean;
   updateMutableFields(
     id: number,
     fields: {

package/lib/mollie/orm/invoices_orm.js

@@ -5,6 +5,10 @@ const orm_1 = require('../../core/orm/orm');
 class InvoicesOrm extends orm_1.ZOrm {
   constructor(opt) {
     super({ sqlService: opt.sqlService, alias: opt.alias ?? 'mollie_invoices' });
+    this.statusLogOrm = opt.statusLogOrm;
+  }
+  setStatusLogOrm(orm) {
+    this.statusLogOrm = orm;
   }
   async create(invoice) {
     const res = await this.sqlService.query(
@@ -79,7 +83,7 @@ class InvoicesOrm extends orm_1.ZOrm {
     });
     return res[0];
   }
-  async updateStatus(id, status, amount_paid, paid_at) {
+  async updateStatus(id, status, amount_paid, paid_at, audit) {
     await this.sqlService.query(
       /*SQL*/ `
       UPDATE \`${this.alias}\`
@@ -88,10 +92,21 @@ class InvoicesOrm extends orm_1.ZOrm {
     `,
       { id, status, amount_paid: amount_paid ?? null, paid_at: paid_at ?? null },
     );
+    if (this.statusLogOrm && audit) {
+      await this.statusLogOrm.insert({
+        invoice_id: id,
+        from_status: audit.fromStatus ?? null,
+        to_status: status,
+        actor_type: audit.actorType,
+        mollie_payment_id: audit.molliePaymentId ?? null,
+        note: audit.note ?? null,
+        metadata: audit.metadata ?? null,
+      });
+    }
   }
   /** Transitions status only if the current DB status matches `fromStatus`. Safe against concurrent updates. */
-  async updateStatusConditional(id, status, fromStatus) {
-    await this.sqlService.query(
+  async updateStatusConditional(id, status, fromStatus, audit) {
+    const result = await this.sqlService.query(
       /*SQL*/ `
       UPDATE \`${this.alias}\`
       SET status=:status, updated_at=NOW()
@@ -99,6 +114,19 @@ class InvoicesOrm extends orm_1.ZOrm {
     `,
       { id, status, fromStatus },
     );
+    const changed = result?.affectedRows > 0 || result?.changedRows > 0;
+    if (this.statusLogOrm && changed) {
+      await this.statusLogOrm.insert({
+        invoice_id: id,
+        from_status: fromStatus,
+        to_status: status,
+        actor_type: audit?.actorType ?? 'system',
+        mollie_payment_id: audit?.molliePaymentId ?? null,
+        note: audit?.note ?? null,
+        metadata: audit?.metadata ?? null,
+      });
+    }
+    return changed;
   }
   async updatePaymentRef(id, payload) {
     await this.sqlService.query(
@@ -162,6 +190,29 @@ class InvoicesOrm extends orm_1.ZOrm {
       { id },
     );
   }
+  async setArchivedAt(id) {
+    await this.sqlService.query(
+      /*SQL*/ `
+      UPDATE \`${this.alias}\`
+      SET archived_at=NOW(), updated_at=NOW()
+      WHERE id=:id
+    `,
+      { id },
+    );
+  }
+  async clearArchivedAt(id) {
+    await this.sqlService.query(
+      /*SQL*/ `
+      UPDATE \`${this.alias}\`
+      SET archived_at=NULL, updated_at=NOW()
+      WHERE id=:id
+    `,
+      { id },
+    );
+  }
+  isArchived(invoice) {
+    return invoice.archived_at != null;
+  }
   async updateMutableFields(id, fields) {
     const sets = [];
     const params = { id };
@@ -207,7 +258,7 @@ class InvoicesOrm extends orm_1.ZOrm {
         pay_token_hash CHAR(64),
         pay_token_expires_at DATETIME,
         pay_token_finalized_at DATETIME,
-        status ENUM('draft','pending','paid','failed','canceled','expired','refunded','archived') NOT NULL DEFAULT 'draft',
+        status ENUM('draft','pending','paid','failed','canceled','expired','refunded') NOT NULL DEFAULT 'draft',
         amount_due DECIMAL(12,2) NOT NULL,
         amount_paid DECIMAL(12,2) NOT NULL DEFAULT 0,
         currency CHAR(3) NOT NULL DEFAULT 'EUR',
@@ -218,6 +269,7 @@ class InvoicesOrm extends orm_1.ZOrm {
         paid_at DATETIME,
         checkout_url VARCHAR(512),
         times_sent INT NOT NULL DEFAULT 0,
+        archived_at DATETIME NULL,
         metadata JSON NULL,
         created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
         updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

package/lib/mollie/orm/payment_status_log_orm.d.ts

@@ -0,0 +1,11 @@
+import { ZOrm } from '../../core/orm/orm';
+import { ZSQLService } from '../../core/sql_service';
+import { ZPaymentStatusLogEntry } from '../types/mollie_types';
+export declare class PaymentStatusLogOrm extends ZOrm {
+  constructor(opt: { sqlService: ZSQLService; alias?: string });
+  insert(entry: Omit<ZPaymentStatusLogEntry, 'id' | 'created_at'>): Promise<void>;
+  findByInvoiceId(invoiceId: number): Promise<ZPaymentStatusLogEntry[]>;
+  findByPaymentId(paymentId: number): Promise<ZPaymentStatusLogEntry[]>;
+  findByMolliePaymentId(molliePaymentId: string): Promise<ZPaymentStatusLogEntry[]>;
+  createTable(): Promise<void>;
+}

package/lib/mollie/orm/payment_status_log_orm.js

@@ -0,0 +1,68 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.PaymentStatusLogOrm = void 0;
+const orm_1 = require('../../core/orm/orm');
+class PaymentStatusLogOrm extends orm_1.ZOrm {
+  constructor(opt) {
+    super({ sqlService: opt.sqlService, alias: opt.alias ?? 'mollie_payment_status_log' });
+  }
+  async insert(entry) {
+    await this.sqlService.query(
+      /*SQL*/ `
+      INSERT INTO \`${this.alias}\`
+        (payment_id, invoice_id, mollie_payment_id, from_status, to_status, actor_type, note, metadata)
+      VALUES
+        (:payment_id, :invoice_id, :mollie_payment_id, :from_status, :to_status, :actor_type, :note, :metadata)
+    `,
+      {
+        payment_id: entry.payment_id,
+        invoice_id: entry.invoice_id,
+        mollie_payment_id: entry.mollie_payment_id,
+        from_status: entry.from_status ?? null,
+        to_status: entry.to_status,
+        actor_type: entry.actor_type,
+        note: entry.note ?? null,
+        metadata: entry.metadata != null ? JSON.stringify(entry.metadata) : null,
+      },
+    );
+  }
+  async findByInvoiceId(invoiceId) {
+    return await this.sqlService.exec({
+      query: `SELECT * FROM \`${this.alias}\` WHERE invoice_id=:invoiceId ORDER BY created_at ASC, id ASC`,
+      params: { invoiceId },
+    });
+  }
+  async findByPaymentId(paymentId) {
+    return await this.sqlService.exec({
+      query: `SELECT * FROM \`${this.alias}\` WHERE payment_id=:paymentId ORDER BY created_at ASC, id ASC`,
+      params: { paymentId },
+    });
+  }
+  async findByMolliePaymentId(molliePaymentId) {
+    return await this.sqlService.exec({
+      query: `SELECT * FROM \`${this.alias}\` WHERE mollie_payment_id=:molliePaymentId ORDER BY created_at ASC, id ASC`,
+      params: { molliePaymentId },
+    });
+  }
+  async createTable() {
+    await this.sqlService.query(/*SQL*/ `
+      CREATE TABLE IF NOT EXISTS \`${this.alias}\` (
+        id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+        payment_id BIGINT UNSIGNED NOT NULL,
+        invoice_id BIGINT UNSIGNED NOT NULL,
+        mollie_payment_id VARCHAR(64) NOT NULL,
+        from_status ENUM('open','pending','authorized','paid','canceled','expired','failed','refunded') NULL,
+        to_status ENUM('open','pending','authorized','paid','canceled','expired','failed','refunded') NOT NULL,
+        actor_type ENUM('webhook','system','admin') NOT NULL,
+        note VARCHAR(512) NULL,
+        metadata JSON NULL,
+        created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        KEY idx_pay_status_log_payment (payment_id),
+        KEY idx_pay_status_log_invoice (invoice_id),
+        KEY idx_pay_status_log_invoice_time (invoice_id, created_at),
+        KEY idx_pay_status_log_mollie (mollie_payment_id)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
+    `);
+  }
+}
+exports.PaymentStatusLogOrm = PaymentStatusLogOrm;

package/lib/mollie/services/invoice_audit_service.d.ts

@@ -0,0 +1,38 @@
+import { ZSQLService } from '../../core/sql_service';
+import { InvoiceStatusLogOrm } from '../orm/invoice_status_log_orm';
+import { PaymentStatusLogOrm } from '../orm/payment_status_log_orm';
+import { ZInvoiceStatusLogEntry, ZPaymentStatusLogEntry, ZInvoiceTimelineEvent } from '../types/mollie_types';
+export declare class InvoiceAuditService {
+  private invoiceStatusLogOrm;
+  private paymentStatusLogOrm;
+  private sqlService;
+  constructor(opt: {
+    sqlService: ZSQLService;
+    invoiceStatusLogOrm?: InvoiceStatusLogOrm;
+    paymentStatusLogOrm?: PaymentStatusLogOrm;
+  });
+  /** Ensure audit log tables exist */
+  autoInit(): Promise<void>;
+  get statusLogOrm(): InvoiceStatusLogOrm;
+  get paymentLogOrm(): PaymentStatusLogOrm;
+  /** Returns all invoice-level status transitions for a given invoice */
+  getInvoiceStatusHistory(invoiceId: number): Promise<ZInvoiceStatusLogEntry[]>;
+  /** Returns all payment-level status transitions for a given invoice */
+  getPaymentStatusHistory(invoiceId: number): Promise<ZPaymentStatusLogEntry[]>;
+  /** Returns all status transitions for a single Mollie payment */
+  getPaymentHistory(molliePaymentId: string): Promise<ZPaymentStatusLogEntry[]>;
+  /**
+   * Returns a unified, chronologically ordered timeline of all status changes
+   * (both invoice-level and payment-level) for a given invoice.
+   */
+  getInvoiceTimeline(invoiceId: number): Promise<ZInvoiceTimelineEvent[]>;
+  /**
+   * Backfills audit log entries from existing invoices and payments.
+   * Uses `created_at` for initial status and `paid_at` for paid transitions.
+   * Idempotent — skips entities that already have log entries.
+   */
+  backfillAuditLog(opt?: { invoicesTable?: string; paymentsTable?: string }): Promise<{
+    invoicesCreated: number;
+    paymentsCreated: number;
+  }>;
+}

package/lib/mollie/services/invoice_audit_service.js

@@ -0,0 +1,178 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.InvoiceAuditService = void 0;
+const invoice_status_log_orm_1 = require('../orm/invoice_status_log_orm');
+const payment_status_log_orm_1 = require('../orm/payment_status_log_orm');
+class InvoiceAuditService {
+  constructor(opt) {
+    this.sqlService = opt.sqlService;
+    this.invoiceStatusLogOrm =
+      opt.invoiceStatusLogOrm ?? new invoice_status_log_orm_1.InvoiceStatusLogOrm({ sqlService: opt.sqlService });
+    this.paymentStatusLogOrm =
+      opt.paymentStatusLogOrm ?? new payment_status_log_orm_1.PaymentStatusLogOrm({ sqlService: opt.sqlService });
+  }
+  /** Ensure audit log tables exist */
+  async autoInit() {
+    await this.invoiceStatusLogOrm.ensureTableExists();
+    await this.paymentStatusLogOrm.ensureTableExists();
+  }
+  get statusLogOrm() {
+    return this.invoiceStatusLogOrm;
+  }
+  get paymentLogOrm() {
+    return this.paymentStatusLogOrm;
+  }
+  // ==================== Query API ====================
+  /** Returns all invoice-level status transitions for a given invoice */
+  async getInvoiceStatusHistory(invoiceId) {
+    return await this.invoiceStatusLogOrm.findByInvoiceId(invoiceId);
+  }
+  /** Returns all payment-level status transitions for a given invoice */
+  async getPaymentStatusHistory(invoiceId) {
+    return await this.paymentStatusLogOrm.findByInvoiceId(invoiceId);
+  }
+  /** Returns all status transitions for a single Mollie payment */
+  async getPaymentHistory(molliePaymentId) {
+    return await this.paymentStatusLogOrm.findByMolliePaymentId(molliePaymentId);
+  }
+  /**
+   * Returns a unified, chronologically ordered timeline of all status changes
+   * (both invoice-level and payment-level) for a given invoice.
+   */
+  async getInvoiceTimeline(invoiceId) {
+    const invLog = this.invoiceStatusLogOrm.alias;
+    const payLog = this.paymentStatusLogOrm.alias;
+    const rows = await this.sqlService.exec({
+      query: /*SQL*/ `
+        SELECT
+          'invoice_status' AS event_type,
+          from_status,
+          to_status,
+          actor_type,
+          mollie_payment_id,
+          note,
+          metadata,
+          created_at,
+          id AS sort_id
+        FROM \`${invLog}\`
+        WHERE invoice_id = :invoiceId
+
+        UNION ALL
+
+        SELECT
+          'payment_status' AS event_type,
+          from_status,
+          to_status,
+          actor_type,
+          mollie_payment_id,
+          note,
+          metadata,
+          created_at,
+          id AS sort_id
+        FROM \`${payLog}\`
+        WHERE invoice_id = :invoiceId
+
+        ORDER BY created_at ASC, sort_id ASC
+      `,
+      params: { invoiceId },
+    });
+    return rows.map((r) => ({
+      event_type: r.event_type,
+      from_status: r.from_status,
+      to_status: r.to_status,
+      actor_type: r.actor_type,
+      mollie_payment_id: r.mollie_payment_id,
+      note: r.note,
+      metadata: typeof r.metadata === 'string' ? JSON.parse(r.metadata) : r.metadata,
+      created_at: r.created_at,
+    }));
+  }
+  // ==================== Backfill ====================
+  /**
+   * Backfills audit log entries from existing invoices and payments.
+   * Uses `created_at` for initial status and `paid_at` for paid transitions.
+   * Idempotent — skips entities that already have log entries.
+   */
+  async backfillAuditLog(opt) {
+    const invTable = opt?.invoicesTable ?? 'mollie_invoices';
+    const payTable = opt?.paymentsTable ?? 'mollie_invoice_payments';
+    const invLog = this.invoiceStatusLogOrm.alias;
+    const payLog = this.paymentStatusLogOrm.alias;
+    let invoicesCreated = 0;
+    let paymentsCreated = 0;
+    // --- Invoice status backfill ---
+    const invoices = await this.sqlService.exec({
+      query: `SELECT id, status, paid_at, created_at FROM \`${invTable}\` ORDER BY id ASC`,
+    });
+    for (const inv of invoices) {
+      // Check if already backfilled
+      const existing = await this.sqlService.exec({
+        query: `SELECT COUNT(*) AS cnt FROM \`${invLog}\` WHERE invoice_id = :id`,
+        params: { id: inv.id },
+      });
+      if (existing[0]?.cnt > 0) continue;
+      // Insert creation entry
+      await this.sqlService.query(
+        /*SQL*/ `
+        INSERT INTO \`${invLog}\` (invoice_id, from_status, to_status, actor_type, note, created_at)
+        VALUES (:id, NULL, :status, 'system', 'Backfilled from existing data', :created_at)
+      `,
+        { id: inv.id, status: inv.status, created_at: inv.created_at },
+      );
+      invoicesCreated++;
+      // If paid and has a paid_at timestamp different from created_at, add a paid transition
+      if (inv.status === 'paid' && inv.paid_at && inv.paid_at !== inv.created_at) {
+        await this.sqlService.query(
+          /*SQL*/ `
+          INSERT INTO \`${invLog}\` (invoice_id, from_status, to_status, actor_type, note, created_at)
+          VALUES (:id, 'pending', 'paid', 'system', 'Backfilled from paid_at', :paid_at)
+        `,
+          { id: inv.id, paid_at: inv.paid_at },
+        );
+        invoicesCreated++;
+      }
+    }
+    // --- Payment status backfill ---
+    const payments = await this.sqlService.exec({
+      query: `SELECT id, invoice_id, mollie_payment_id, status, paid_at, created_at FROM \`${payTable}\` ORDER BY id ASC`,
+    });
+    for (const pay of payments) {
+      const existing = await this.sqlService.exec({
+        query: `SELECT COUNT(*) AS cnt FROM \`${payLog}\` WHERE payment_id = :id`,
+        params: { id: pay.id },
+      });
+      if (existing[0]?.cnt > 0) continue;
+      await this.sqlService.query(
+        /*SQL*/ `
+        INSERT INTO \`${payLog}\` (payment_id, invoice_id, mollie_payment_id, from_status, to_status, actor_type, note, created_at)
+        VALUES (:id, :invoice_id, :mollie_payment_id, NULL, :status, 'system', 'Backfilled from existing data', :created_at)
+      `,
+        {
+          id: pay.id,
+          invoice_id: pay.invoice_id,
+          mollie_payment_id: pay.mollie_payment_id,
+          status: pay.status,
+          created_at: pay.created_at,
+        },
+      );
+      paymentsCreated++;
+      if (pay.status === 'paid' && pay.paid_at && pay.paid_at !== pay.created_at) {
+        await this.sqlService.query(
+          /*SQL*/ `
+          INSERT INTO \`${payLog}\` (payment_id, invoice_id, mollie_payment_id, from_status, to_status, actor_type, note, created_at)
+          VALUES (:id, :invoice_id, :mollie_payment_id, 'open', 'paid', 'system', 'Backfilled from paid_at', :paid_at)
+        `,
+          {
+            id: pay.id,
+            invoice_id: pay.invoice_id,
+            mollie_payment_id: pay.mollie_payment_id,
+            paid_at: pay.paid_at,
+          },
+        );
+        paymentsCreated++;
+      }
+    }
+    return { invoicesCreated, paymentsCreated };
+  }
+}
+exports.InvoiceAuditService = InvoiceAuditService;

package/lib/mollie/services/invoice_service.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 import { CustomerService } from './customer_service';
+import { InvoiceAuditService } from './invoice_audit_service';
 import { RenderData } from '../../core/types/site_config';
 import { ZMailService } from '../../core/mail_service';
 import { MollieService } from './mollie_service';
@@ -22,6 +23,9 @@ export declare class InvoiceService {
   private templateOrm;
   private subscriptionsOrm;
   private subscriptionItemsOrm;
+  private invoiceStatusLogOrm;
+  private paymentStatusLogOrm;
+  private auditService;
   private payTokenSecret;
   private payTokenLifetimeMs;
   private mailService;
@@ -39,12 +43,14 @@ export declare class InvoiceService {
     invoiceNumberMode?: 'sequence' | 'id';
     invoiceNumberFormat?: (id: number) => string;
   });
+  /** Returns the audit service for querying audit logs and timeline */
+  getAuditService(): InvoiceAuditService;
   autoInit(): Promise<void>;
   private ensurePayTokenSchema;
   private ensureSubscriptionInvoiceSchema;
   private ensureSubsidyItemTypeSchema;
   private ensureSentCountSchema;
-  private ensureArchivedStatusSchema;
+  private ensureArchivedAtSchema;
   private ensureInvoicePaymentSchema;
   private generateInvoiceNumber;
   private getWebhookUrl;
@@ -82,6 +88,7 @@ export declare class InvoiceService {
     },
   ): Promise<ZInvoice>;
   archiveInvoice(invoiceId: number): Promise<ZInvoice>;
+  unarchiveInvoice(invoiceId: number): Promise<ZInvoice>;
   duplicateInvoice(
     sourceInvoiceId: number,
     customerId: number,

package/lib/mollie/services/invoice_service.js

@@ -16,6 +16,9 @@ const invoice_payments_orm_1 = require('../orm/invoice_payments_orm');
 const invoices_orm_1 = require('../orm/invoices_orm');
 const subscription_items_orm_1 = require('../orm/subscription_items_orm');
 const subscriptions_orm_1 = require('../orm/subscriptions_orm');
+const invoice_status_log_orm_1 = require('../orm/invoice_status_log_orm');
+const payment_status_log_orm_1 = require('../orm/payment_status_log_orm');
+const invoice_audit_service_1 = require('./invoice_audit_service');
 const subscription_utils_1 = require('../util/subscription_utils');
 const orm_1 = require('../../core/orm/orm');
 class InvoiceService {
@@ -29,27 +32,45 @@ class InvoiceService {
     this.opt = opt;
     this.payTokenSecret = this.opt.payTokenSecret || '';
     this.payTokenLifetimeMs = 60 * 24 * 60 * 60 * 1000;
-    this.invoicesOrm = new invoices_orm_1.InvoicesOrm({ sqlService: opt.sqlService });
+    this.invoiceStatusLogOrm = new invoice_status_log_orm_1.InvoiceStatusLogOrm({ sqlService: opt.sqlService });
+    this.paymentStatusLogOrm = new payment_status_log_orm_1.PaymentStatusLogOrm({ sqlService: opt.sqlService });
+    this.invoicesOrm = new invoices_orm_1.InvoicesOrm({
+      sqlService: opt.sqlService,
+      statusLogOrm: this.invoiceStatusLogOrm,
+    });
     this.itemsOrm = new invoice_items_orm_1.InvoiceItemsOrm({ sqlService: opt.sqlService });
-    this.paymentsOrm = new invoice_payments_orm_1.InvoicePaymentsOrm({ sqlService: opt.sqlService });
+    this.paymentsOrm = new invoice_payments_orm_1.InvoicePaymentsOrm({
+      sqlService: opt.sqlService,
+      paymentLogOrm: this.paymentStatusLogOrm,
+    });
     this.templateOrm = new invoice_item_templates_orm_1.InvoiceItemTemplatesOrm({ sqlService: opt.sqlService });
     this.subscriptionsOrm = new subscriptions_orm_1.SubscriptionsOrm({ sqlService: opt.sqlService });
     this.subscriptionItemsOrm = new subscription_items_orm_1.SubscriptionItemsOrm({ sqlService: opt.sqlService });
+    this.auditService = new invoice_audit_service_1.InvoiceAuditService({
+      sqlService: opt.sqlService,
+      invoiceStatusLogOrm: this.invoiceStatusLogOrm,
+      paymentStatusLogOrm: this.paymentStatusLogOrm,
+    });
     this.mailService = opt.mailService;
     this.invoiceNumberMode = opt.invoiceNumberMode ?? 'sequence';
     this.invoiceNumberFormat = opt.invoiceNumberFormat ?? ((id) => `INV-${id.toString().padStart(6, '0')}`);
   }
+  /** Returns the audit service for querying audit logs and timeline */
+  getAuditService() {
+    return this.auditService;
+  }
   async autoInit() {
     await this.invoicesOrm.ensureTableExists();
     await this.itemsOrm.ensureTableExists();
     await this.paymentsOrm.ensureTableExists();
     await this.templateOrm.ensureTableExists();
+    await this.auditService.autoInit();
     await this.ensurePayTokenSchema();
     await this.ensureSubscriptionInvoiceSchema();
     await this.ensureInvoicePaymentSchema();
     await this.ensureSubsidyItemTypeSchema();
     await this.ensureSentCountSchema();
-    await this.ensureArchivedStatusSchema();
+    await this.ensureArchivedAtSchema();
   }
   async ensurePayTokenSchema() {
     const table = this.invoicesOrm.alias;
@@ -121,17 +142,14 @@ class InvoiceService {
       );
     }
   }
-  async ensureArchivedStatusSchema() {
+  async ensureArchivedAtSchema() {
     const table = this.invoicesOrm.alias;
     const rows = await this.opt.sqlService.exec({
-      query: `SELECT COLUMN_TYPE FROM information_schema.COLUMNS WHERE TABLE_SCHEMA=:schema AND TABLE_NAME=:tableName AND COLUMN_NAME='status' LIMIT 1`,
+      query: `SELECT COLUMN_NAME FROM information_schema.COLUMNS WHERE TABLE_SCHEMA=:schema AND TABLE_NAME=:tableName AND COLUMN_NAME='archived_at' LIMIT 1`,
       params: { schema: this.opt.sqlService.database, tableName: table },
     });
-    const colType = rows?.[0]?.COLUMN_TYPE ?? '';
-    if (colType && !colType.includes('archived')) {
-      await this.opt.sqlService.query(
-        `ALTER TABLE \`${table}\` MODIFY COLUMN status ENUM('draft','pending','paid','failed','canceled','expired','refunded','archived') NOT NULL DEFAULT 'draft'`,
-      );
+    if (!rows?.[0]) {
+      await this.opt.sqlService.query(`ALTER TABLE \`${table}\` ADD COLUMN archived_at DATETIME NULL AFTER times_sent`);
     }
   }
   async ensureInvoicePaymentSchema() {
@@ -314,20 +332,23 @@ class InvoiceService {
       sequenceType: opt?.sequenceType ?? 'oneoff',
       mandateId: opt?.mandateId ?? undefined,
     });
-    await this.paymentsOrm.upsert({
-      invoice_id: invoice.id,
-      mollie_payment_id: payment.id,
-      status: payment.status,
-      sequence_type: payment.sequenceType ?? opt?.sequenceType ?? 'oneoff',
-      mollie_subscription_id: payment.subscriptionId ?? null,
-      method: payment.method ?? null,
-      amount: Number(payment.amount.value),
-      currency: payment.amount.currency,
-      checkout_url: payment?._links?.checkout?.href ?? null,
-      paid_at: (0, orm_1.toDatetime)(payment.paidAt ?? null),
-      expires_at: (0, orm_1.toDatetime)(payment.expiresAt),
-      mandate_id: payment.mandateId ?? opt?.mandateId ?? null,
-    });
+    await this.paymentsOrm.upsert(
+      {
+        invoice_id: invoice.id,
+        mollie_payment_id: payment.id,
+        status: payment.status,
+        sequence_type: payment.sequenceType ?? opt?.sequenceType ?? 'oneoff',
+        mollie_subscription_id: payment.subscriptionId ?? null,
+        method: payment.method ?? null,
+        amount: Number(payment.amount.value),
+        currency: payment.amount.currency,
+        checkout_url: payment?._links?.checkout?.href ?? null,
+        paid_at: (0, orm_1.toDatetime)(payment.paidAt ?? null),
+        expires_at: (0, orm_1.toDatetime)(payment.expiresAt),
+        mandate_id: payment.mandateId ?? opt?.mandateId ?? null,
+      },
+      { actorType: 'system', note: 'Payment created via Mollie API' },
+    );
     await this.invoicesOrm.updatePaymentRef(invoice.id, {
       mollie_payment_id: payment.id,
       checkout_url: payment?.getCheckoutUrl() ?? payment?._links?.checkout?.href ?? null,
@@ -427,6 +448,8 @@ class InvoiceService {
     if (!invoice) throw new Error(`Invoice ${invoiceId} not found`);
     if (invoice.status !== 'draft')
       throw new Error(`Invoice ${invoice.invoice_number} cannot be edited (status: ${invoice.status})`);
+    if (this.invoicesOrm.isArchived(invoice))
+      throw new Error(`Invoice ${invoice.invoice_number} cannot be edited (archived)`);
     if ((invoice.times_sent ?? 0) > 0)
       throw new Error(
         `Invoice ${invoice.invoice_number} cannot be edited (already sent ${invoice.times_sent} time(s))`,
@@ -460,13 +483,37 @@ class InvoiceService {
     if (!invoice) {
       throw new Error(`Invoice ${invoiceId} not found`);
     }
-    if (invoice.status === 'paid') {
-      throw new Error(`Cannot archive a paid invoice (${invoice.invoice_number})`);
+    if (this.invoicesOrm.isArchived(invoice)) {
+      return invoice;
+    }
+    await this.invoicesOrm.setArchivedAt(invoiceId);
+    // Audit log: record archive event
+    await this.invoiceStatusLogOrm.insert({
+      invoice_id: invoiceId,
+      from_status: invoice.status,
+      to_status: invoice.status,
+      actor_type: 'admin',
+      note: 'Invoice archived (archived_at set)',
+    });
+    return await this.invoicesOrm.findById(invoiceId);
+  }
+  async unarchiveInvoice(invoiceId) {
+    const invoice = await this.invoicesOrm.findById(invoiceId);
+    if (!invoice) {
+      throw new Error(`Invoice ${invoiceId} not found`);
     }
-    if (invoice.status === 'archived') {
+    if (!this.invoicesOrm.isArchived(invoice)) {
       return invoice;
     }
-    await this.invoicesOrm.updateStatus(invoiceId, 'archived');
+    await this.invoicesOrm.clearArchivedAt(invoiceId);
+    // Audit log: record unarchive event
+    await this.invoiceStatusLogOrm.insert({
+      invoice_id: invoiceId,
+      from_status: invoice.status,
+      to_status: invoice.status,
+      actor_type: 'admin',
+      note: 'Invoice unarchived (archived_at cleared)',
+    });
     return await this.invoicesOrm.findById(invoiceId);
   }
   // ==================== Duplicate ====================
@@ -566,6 +613,15 @@ class InvoiceService {
     if (!savedInvoice) {
       throw new Error('Failed to persist invoice');
     }
+    // Audit log: record initial invoice creation status
+    await this.invoiceStatusLogOrm.insert({
+      invoice_id: savedInvoice.id,
+      from_status: null,
+      to_status: status,
+      actor_type: 'system',
+      mollie_payment_id: overrides?.mollie_payment_id ?? null,
+      note: 'Invoice created',
+    });
     const itemsWithInvoice = items.map((it) => ({ ...it, invoice_id: savedInvoice.id }));
     await this.itemsOrm.bulkInsert(itemsWithInvoice);
     const pay = overrides?.issuePayToken === false ? null : await this.ensurePayLink(savedInvoice.id);
@@ -649,26 +705,34 @@ class InvoiceService {
     if (!invoice) {
       throw new Error(`Invoice for payment ${paymentId} not found`);
     }
-    await this.paymentsOrm.upsert({
-      invoice_id: invoice.id,
-      mollie_payment_id: payment.id,
-      status: payment.status,
-      sequence_type: payment.sequenceType ?? null,
-      mollie_subscription_id: payment.subscriptionId ?? null,
-      method: payment.method ?? null,
-      amount: Number(payment.amount.value),
-      currency: payment.amount.currency,
-      checkout_url: payment?._links?.checkout?.href ?? null,
-      paid_at: (0, orm_1.toDatetime)(payment.paidAt ?? null),
-      expires_at: (0, orm_1.toDatetime)(payment.expiresAt),
-      mandate_id: payment.mandateId ?? null,
-    });
+    await this.paymentsOrm.upsert(
+      {
+        invoice_id: invoice.id,
+        mollie_payment_id: payment.id,
+        status: payment.status,
+        sequence_type: payment.sequenceType ?? null,
+        mollie_subscription_id: payment.subscriptionId ?? null,
+        method: payment.method ?? null,
+        amount: Number(payment.amount.value),
+        currency: payment.amount.currency,
+        checkout_url: payment?._links?.checkout?.href ?? null,
+        paid_at: (0, orm_1.toDatetime)(payment.paidAt ?? null),
+        expires_at: (0, orm_1.toDatetime)(payment.expiresAt),
+        mandate_id: payment.mandateId ?? null,
+      },
+      { actorType: 'webhook', note: 'Synced from Mollie webhook' },
+    );
     await this.invoicesOrm.updatePaymentRef(invoice.id, {
       mollie_payment_id: payment.id,
       checkout_url: payment?._links?.checkout?.href ?? null,
     });
     const previousStatus = invoice.status;
-    await this.invoicesOrm.updateStatus(invoice.id, mappedStatus, paidAmount, paidAt);
+    await this.invoicesOrm.updateStatus(invoice.id, mappedStatus, paidAmount, paidAt, {
+      fromStatus: previousStatus,
+      actorType: 'webhook',
+      molliePaymentId: payment.id,
+      note: `Synced from Mollie webhook (mollie status: ${payment.status})`,
+    });
     if (mappedStatus === 'paid') {
       await this.invoicesOrm.finalizePayToken(invoice.id);
     }
@@ -1011,7 +1075,10 @@ class InvoiceService {
     });
     await this.invoicesOrm.incrementTimesSent(invoiceId);
     if (!isReceipt) {
-      await this.invoicesOrm.updateStatusConditional(invoiceId, 'pending', 'draft');
+      await this.invoicesOrm.updateStatusConditional(invoiceId, 'pending', 'draft', {
+        actorType: 'system',
+        note: 'Status set to pending after invoice email sent',
+      });
     }
     return {
       invoice_number: invoice.invoice_number,

package/lib/mollie/types/mollie_types.d.ts

@@ -18,7 +18,7 @@ export type ZCustomer = {
   updated_at?: string | Date;
 };
 export type ZInvoiceItemType = 'service' | 'subsidy';
-export type ZInvoiceStatus = 'draft' | 'pending' | 'paid' | 'failed' | 'canceled' | 'expired' | 'refunded' | 'archived';
+export type ZInvoiceStatus = 'draft' | 'pending' | 'paid' | 'failed' | 'canceled' | 'expired' | 'refunded';
 export type ZInvoiceItem = {
   id?: number;
   invoice_id: number;
@@ -77,6 +77,7 @@ export type ZInvoice = {
   paid_at?: string | null;
   checkout_url?: string | null;
   times_sent?: number;
+  archived_at?: string | null;
   metadata?: any;
   created_at?: string | Date;
   updated_at?: string | Date;
@@ -173,6 +174,47 @@ export type ZPayResolveResult =
       action: 'paid';
       invoice: ZInvoice;
     };
+export type ZAuditActorType = 'webhook' | 'system' | 'admin';
+export type ZInvoiceStatusLogEntry = {
+  id?: number;
+  invoice_id: number;
+  from_status: ZInvoiceStatus | null;
+  to_status: ZInvoiceStatus;
+  actor_type: ZAuditActorType;
+  mollie_payment_id?: string | null;
+  note?: string | null;
+  metadata?: any;
+  created_at?: string | Date;
+};
+export type ZPaymentStatusLogEntry = {
+  id?: number;
+  payment_id: number;
+  invoice_id: number;
+  mollie_payment_id: string;
+  from_status: ZInvoicePaymentStatus | null;
+  to_status: ZInvoicePaymentStatus;
+  actor_type: ZAuditActorType;
+  note?: string | null;
+  metadata?: any;
+  created_at?: string | Date;
+};
+export type ZInvoiceTimelineEvent = {
+  event_type: 'invoice_status' | 'payment_status';
+  from_status: string | null;
+  to_status: string;
+  actor_type: ZAuditActorType;
+  mollie_payment_id?: string | null;
+  note?: string | null;
+  metadata?: any;
+  created_at: string | Date;
+};
+export type ZAuditContext = {
+  fromStatus?: string | null;
+  actorType: ZAuditActorType;
+  molliePaymentId?: string | null;
+  note?: string | null;
+  metadata?: any;
+};
 export type RecoveryStats = {
   dryRun: boolean;
   startedAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ztechno_core",
-  "version": "0.0.131",
+  "version": "0.0.133",
   "description": "Core files for ztechno framework",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",