@managemint-solutions/entities 1.23.1 → 1.24.0

package/dist/billing/enum/index.d.ts

@@ -15,7 +15,19 @@ export declare enum BillingTransactionType {
     INITIAL = "initial",
     PRORATA = "prorata",
     RENEWAL = "renewal",
-    REINSTATEMENT = "reinstatement"
+    REINSTATEMENT = "reinstatement",
+    /**
+     * The small charge Paystack's hosted card-update page makes to tokenise a new
+     * card (metadata.transaction_type = 'update_card'). Paystack refunds it at once;
+     * the row exists so the refund has something to land on. Never an invoice.
+     */
+    CARD_VERIFICATION = "card_verification",
+    /**
+     * Money that landed but matched nothing we recognise: no tag of ours, no Paystack
+     * hosted-page tag, no plan matching the organization's. Recorded ledger-first with an
+     * alert; it never moves billing status, seats or modules.
+     */
+    UNCLASSIFIED = "unclassified"
 }
 export declare enum BillingTransactionStatus {
     INITIALIZED = "initialized",
@@ -24,7 +36,16 @@ export declare enum BillingTransactionStatus {
     PAID = "paid",
     FAILED = "failed",
     CANCELLED = "cancelled",
-    EXPIRED = "expired"
+    EXPIRED = "expired",
+    /** Paystack has accepted a refund of a paid row (refund.pending / refund.processing). */
+    REFUND_PENDING = "refund_pending",
+    /** The refund settled (refund.processed); refunded_at and refund_amount_minor are set. */
+    REFUNDED = "refunded",
+    /**
+     * A renewal Paystack has announced (invoice.create) but not yet charged. Not an open
+     * transaction: it never holds the one-open-transaction slot.
+     */
+    SCHEDULED = "scheduled"
 }
 export declare enum PaystackWebhookProcessingStatus {
     RECEIVED = "received",
@@ -78,5 +99,23 @@ export declare enum BillingEventType {
     SUBSCRIPTION_CANCELLED = "subscription_cancelled",
     CARD_EXPIRING_SOON = "card_expiring_soon",
     WEBHOOK_IGNORED_STALE_SUBSCRIPTION = "webhook_ignored_stale_subscription",
-    SEAT_RELEASED = "seat_released"
+    SEAT_RELEASED = "seat_released",
+    /** invoice.payment_failed wrote the failed renewal to the ledger and issued its invoice as failed. */
+    RENEWAL_FAILED_RECORDED = "renewal_failed_recorded",
+    /** A charge.success from Paystack's card-update page was recorded as a card verification, not a renewal. */
+    CARD_VERIFICATION_RECORDED = "card_verification_recorded",
+    /** A refund event moved a ledger row; details carry the Paystack refund status. */
+    REFUND_RECORDED = "refund_recorded",
+    REFUND_FAILED = "refund_failed",
+    /** The api charged the saved card for a failed renewal invoice (after a card update or on request). */
+    RENEWAL_RETRY_CHARGED = "renewal_retry_charged",
+    RENEWAL_RETRY_FAILED = "renewal_retry_failed",
+    /** invoice.create opened a scheduled renewal row and invoice for the coming charge. */
+    RENEWAL_SCHEDULED = "renewal_scheduled",
+    /** invoice.update linked Paystack's invoice code and period onto a renewal the charge had already settled. */
+    RENEWAL_INVOICE_LINKED = "renewal_invoice_linked",
+    /** A charge.success matched nothing we recognise and was recorded as unclassified. */
+    UNCLASSIFIED_CHARGE_RECORDED = "unclassified_charge_recorded",
+    /** A retry found a row stuck in pending_payment and settled it from Paystack's verify answer. */
+    RENEWAL_RETRY_RECONCILED = "renewal_retry_reconciled"
 }

package/dist/billing/enum/index.js

@@ -22,6 +22,18 @@ var BillingTransactionType;
     BillingTransactionType["PRORATA"] = "prorata";
     BillingTransactionType["RENEWAL"] = "renewal";
     BillingTransactionType["REINSTATEMENT"] = "reinstatement";
+    /**
+     * The small charge Paystack's hosted card-update page makes to tokenise a new
+     * card (metadata.transaction_type = 'update_card'). Paystack refunds it at once;
+     * the row exists so the refund has something to land on. Never an invoice.
+     */
+    BillingTransactionType["CARD_VERIFICATION"] = "card_verification";
+    /**
+     * Money that landed but matched nothing we recognise: no tag of ours, no Paystack
+     * hosted-page tag, no plan matching the organization's. Recorded ledger-first with an
+     * alert; it never moves billing status, seats or modules.
+     */
+    BillingTransactionType["UNCLASSIFIED"] = "unclassified";
 })(BillingTransactionType || (exports.BillingTransactionType = BillingTransactionType = {}));
 ;
 var BillingTransactionStatus;
@@ -33,6 +45,15 @@ var BillingTransactionStatus;
     BillingTransactionStatus["FAILED"] = "failed";
     BillingTransactionStatus["CANCELLED"] = "cancelled";
     BillingTransactionStatus["EXPIRED"] = "expired";
+    /** Paystack has accepted a refund of a paid row (refund.pending / refund.processing). */
+    BillingTransactionStatus["REFUND_PENDING"] = "refund_pending";
+    /** The refund settled (refund.processed); refunded_at and refund_amount_minor are set. */
+    BillingTransactionStatus["REFUNDED"] = "refunded";
+    /**
+     * A renewal Paystack has announced (invoice.create) but not yet charged. Not an open
+     * transaction: it never holds the one-open-transaction slot.
+     */
+    BillingTransactionStatus["SCHEDULED"] = "scheduled";
 })(BillingTransactionStatus || (exports.BillingTransactionStatus = BillingTransactionStatus = {}));
 ;
 var PaystackWebhookProcessingStatus;
@@ -93,5 +114,23 @@ var BillingEventType;
     BillingEventType["CARD_EXPIRING_SOON"] = "card_expiring_soon";
     BillingEventType["WEBHOOK_IGNORED_STALE_SUBSCRIPTION"] = "webhook_ignored_stale_subscription";
     BillingEventType["SEAT_RELEASED"] = "seat_released";
+    /** invoice.payment_failed wrote the failed renewal to the ledger and issued its invoice as failed. */
+    BillingEventType["RENEWAL_FAILED_RECORDED"] = "renewal_failed_recorded";
+    /** A charge.success from Paystack's card-update page was recorded as a card verification, not a renewal. */
+    BillingEventType["CARD_VERIFICATION_RECORDED"] = "card_verification_recorded";
+    /** A refund event moved a ledger row; details carry the Paystack refund status. */
+    BillingEventType["REFUND_RECORDED"] = "refund_recorded";
+    BillingEventType["REFUND_FAILED"] = "refund_failed";
+    /** The api charged the saved card for a failed renewal invoice (after a card update or on request). */
+    BillingEventType["RENEWAL_RETRY_CHARGED"] = "renewal_retry_charged";
+    BillingEventType["RENEWAL_RETRY_FAILED"] = "renewal_retry_failed";
+    /** invoice.create opened a scheduled renewal row and invoice for the coming charge. */
+    BillingEventType["RENEWAL_SCHEDULED"] = "renewal_scheduled";
+    /** invoice.update linked Paystack's invoice code and period onto a renewal the charge had already settled. */
+    BillingEventType["RENEWAL_INVOICE_LINKED"] = "renewal_invoice_linked";
+    /** A charge.success matched nothing we recognise and was recorded as unclassified. */
+    BillingEventType["UNCLASSIFIED_CHARGE_RECORDED"] = "unclassified_charge_recorded";
+    /** A retry found a row stuck in pending_payment and settled it from Paystack's verify answer. */
+    BillingEventType["RENEWAL_RETRY_RECONCILED"] = "renewal_retry_reconciled";
 })(BillingEventType || (exports.BillingEventType = BillingEventType = {}));
 ;

package/dist/billing/invoices/index.d.ts

@@ -33,6 +33,8 @@ export type InvoiceSummary = {
 export type InvoiceEntity = InvoiceSummary & {
     billing_transaction_id: string;
     paystack_reference: string | null;
+    /** Paystack's INV_… code for a subscription renewal; null for an invoice Paystack never named. */
+    paystack_invoice_code: string | null;
     period_start: string | null;
     period_end: string | null;
     line_items: InvoiceLineItem[];

package/dist/billing/payments/index.d.ts

@@ -14,6 +14,10 @@ export type PaymentSummary = {
     currency: string;
     paid_at: string | null;
     failure_reason: string | null;
+    /** Set when the row is `refunded`; null otherwise. */
+    refunded_at: string | null;
+    /** Minor units Paystack refunded; null until a refund settles. */
+    refund_amount_minor: number | null;
 };
 /** The full payment record behind GET /billing/payments/:paymentId. */
 export type PaymentEntity = PaymentSummary & {

package/dist/paystack/webhook/index.d.ts

@@ -242,6 +242,22 @@ export type PaystackSubscriptionsWithExpiringCardsEvent = {
         }
     ];
 };
+/** The metadata block on a charge the api initialized (principle 4's round trip). */
+export type PaystackOwnChargeMetadata = {
+    organization_id: string;
+    idempotencyKey: string;
+    transactionId: string;
+};
+/** The metadata block Paystack's own hosted pages attach, e.g. the card-update page. */
+export type PaystackHostedPageChargeMetadata = {
+    /** 'update_card' on the card-update page's tokenising charge. */
+    transaction_type?: string;
+    custom_fields?: {
+        display_name: string;
+        variable_name: string;
+        value: string;
+    }[];
+};
 export type PaystackTransactionSuccessfulEvent = {
     event: PaystackWebhookEvent.TRANSACTION_SUCCESSFUL;
     data: {
@@ -258,14 +274,16 @@ export type PaystackTransactionSuccessfulEvent = {
         currency: string;
         ip_address: string;
         /**
-         * Only present on transactions we initialize ourselves. Paystack raises
-         * charge.success for subscription renewals too, and those carry no metadata.
+         * Who raised the charge, read from what the metadata carries:
+         * - `transactionId` and friends: a transaction we initialized ourselves.
+         * - `transaction_type: 'update_card'`: the tokenising charge from Paystack's
+         *   hosted card-update page, which Paystack refunds at once. It also carries
+         *   `custom_fields` naming the subscription code.
+         * - Absent or empty: not ours. A subscription renewal is recognised by `plan`
+         *   naming the organization's plan code, never by the missing metadata alone;
+         *   anything else is recorded as unclassified.
          */
-        metadata?: {
-            organization_id: string;
-            idempotencyKey: string;
-            transactionId: string;
-        };
+        metadata?: PaystackOwnChargeMetadata | PaystackHostedPageChargeMetadata;
         log: {
             time_spent: number;
             attempts: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@managemint-solutions/entities",
-  "version": "1.23.1",
+  "version": "1.24.0",
   "description": "Entity types used by both the api and portal",
   "homepage": "https://github.com/ManageMint-Solutions/managemint-solutions-entities#readme",
   "bugs": {