import { CategoryRow, CustomerRow, OrderRow, ProductImageRow, ProductInventoryRow, ProductRow } from './db/index.js'; /** A customer row as the customer events carry it: never the password hash */ export type CustomerEventRow = Omit; /** * Event registry that maps event names to their data types. * Extend this interface in your modules to register custom events. * * @example * ```typescript * // In your module * declare module '@evershop/evershop/types/event' { * interface EventDataRegistry { * 'order_placed': { * orderId: number; * customerId: number; * total: number; * items: Array<{ productId: number; quantity: number }>; * }; * 'customer_registered': { * customerId: number; * email: string; * name: string; * }; * } * } * ``` */ export interface EventDataRegistry { /** * Fired when a new product is created * Data: Complete product table row */ product_created: ProductRow; /** * Fired when a product is updated * Data: Complete product table row */ product_updated: ProductRow; /** * Fired when a product is deleted * Data: Complete product table row */ product_deleted: ProductRow; /** * Fired after a product duplication — a create whose payload carried * `duplicate_of` — committed and the source's collection memberships were * copied. Subscribe to copy extension-owned product data from the source * to the copy. The regular `product_created` event fires for the copy too; * this event is the source→copy link. */ product_duplicated: { source_product_id: number; source_product_uuid: string; product_id: number; product_uuid: string; }; /** * Fired when a product image is added * Data: Complete product_image table row */ product_image_added: ProductImageRow; /** * Fired when a new category is created * Data: Complete category table row */ category_created: CategoryRow; /** * Fired when a category is updated * Data: Complete category table row */ category_updated: CategoryRow; /** * Fired when a category is deleted * Data: Complete category table row */ category_deleted: CategoryRow; /** * Fired when a product's inventory row changes (a save that changes nothing * fires nothing): an admin save, an order taking stock, a restock, an * import. Written by a database trigger (catalog migration 1.0.17). * Data: the product, and the inventory row before and after the change */ inventory_updated: { product_id: number; product_uuid: string; sku: string; old: ProductInventoryRow; new: ProductInventoryRow; }; /** * Fired when a product goes from out of stock to in stock, together with * `inventory_updated`. In stock is the storefront's rule: stock not * managed, or a quantity above 0 with stock availability on. Written by the * same database trigger. * Data: the product and its inventory now */ product_back_in_stock: { product_id: number; product_uuid: string; sku: string; qty: number; manage_stock: boolean; stock_availability: boolean; }; /** * Fired when a new customer is registered and status = 1 (account is active) * Data: the customer table row, without the password hash */ customer_registered: CustomerEventRow; /** * Fired when a new customer record is added to database, regardless of the status value * Data: the customer table row, without the password hash (customer migration 1.0.7) */ customer_created: CustomerEventRow; /** * Fired when a customer record in database is updated * Data: the customer table row, without the password hash (customer migration 1.0.7) */ customer_updated: CustomerEventRow; /** * Fired when a customer record is deleted * Data: the deleted customer table row, without the password hash (customer migration 1.0.7) */ customer_deleted: CustomerEventRow; /** * Fired when an open cart gets an email, or its email changes: a guest * enters it at checkout, a customer signs in with a cart, a signed-in * customer's cart is created (a database trigger, checkout migration * 1.0.15; the same email saved again fires nothing). For abandoned-cart * emails: build the cart link with `buildCartRecoveryUrl(cart_id)`. The * cart is named by its id, not its uuid, which opens the cart through the * public cart APIs. A guest's email is not verified. */ cart_email_added: { cart_id: number; customer_email: string; customer_id: number | null; }; /** * Fired when a new order record is created in database, regardless of the payment method or order status * Data: Complete order table row */ order_created: OrderRow; /** * Fired once per order when it is placed: the gateway accepts its payment * (authorized or captured; for PayPal, also a capture pending review), or, * for an offline method such as Cash on Delivery, the order is created. The * payment method decides the moment and calls * `markOrderPlaced`, which emits this event with the order row as it is * then (new payment status and `placed_at` included). */ order_placed: OrderRow; /** * Fired when an order status is updated. * Data: { * orderId: number; * before: string; // the previous order status * after: string; // the new order status * } */ order_status_updated: { orderId: number; before: string; after: string; }; /** * Fired once when an order is refunded, in full or in part, by core's refund * recorder — whether the refund originated from the admin refund action or a * gateway refund webhook. Emit-once is guaranteed by the idempotent * refund-transaction insert (admin + webhook echo dedupe to one event). */ order_refunded: { orderId: number; /** This refund's amount, in major currency units. */ amount: number; currency: string; /** True when the cumulative refunded total reaches the captured amount. */ isFullRefund: boolean; /** The gateway's refund transaction id. */ transactionId: string; paymentMethod: string; }; /** * Fired when an order is canceled via `cancelOrder` (any uncaptured * authorization voided, inventory restocked). Carries the cancellation reason * — `order_status_updated{after:'canceled'}` also fires on a cancel, but can't * carry the reason. */ order_canceled: { orderId: number; reason?: string; }; /** * Fired after a shipment row has been inserted by `createShipment` and the * order rollup has been recomputed. The transaction is already committed. * Subscribers (lifecycle emails, webhook bridges) consume this. * `notifyCustomer` reflects the admin's checkbox at creation time — * subscribers must short-circuit when false. */ shipment_created: { shipmentId: number; orderId: number; notifyCustomer: boolean; }; /** * Fired when a shipment transitions to a status whose phase is `delivered`. * Cross-checked against the registry's `phase` field. Always fires; * customer notification gating belongs in the subscriber. */ shipment_delivered: { shipmentId: number; orderId: number; }; /** * Fired on every shipment status write by `updateShipmentStatus`. Carries * both the previous (`from`) and new (`to`) status codes plus the * resolved `phase` of the new state. */ shipment_status_changed: { shipmentId: number; orderId: number; from: string; to: string; phase: 'pending' | 'shipped' | 'delivered' | 'canceled'; }; /** * Fired when a carrier integration successfully purchases a label for a * shipment. `labelUrl` may be null when the carrier returns only a tracking * number (e.g. drop-off providers). */ shipment_label_created: { shipmentId: number; orderId: number; labelUrl: string | null; trackingNumber: string | undefined; }; /** * Fired when an admin voids a previously purchased label via * `voidShipmentLabel`. The tracking number stays on the shipment for * historical record; only the label artifacts (`label_url`, `label_format`) * are cleared. */ shipment_label_voided: { shipmentId: number; orderId: number; trackingNumber: string; }; /** * Fired when a metafield definition is created. * Data: the created metafield_definition (API shape). */ metafield_definition_created: Record; /** * Fired when a metafield definition is updated. * Data: the updated metafield_definition (API shape). */ metafield_definition_updated: Record; /** * Asks for a worker for an import job. Written when a job is ready to be * checked or run (Start, Resume, Check again, a finished upload) and by the * `importDispatch` cron job for a job that keeps waiting. The event process * that claims it starts the worker on its own machine; a request that finds * the machine full is dropped and the cron job asks again. */ import_job_requested: { jobUuid: string; }; /** * Fired when a metafield definition is deleted. Drives per-entity prune * subscribers that strip the key from each owner table's `meta_data`. */ metafield_definition_deleted: { ownerType: string; namespace: string; fieldKey: string; }; } /** * Extract event names from the registry */ export type EventName = keyof EventDataRegistry; /** * Get the data type for a specific event */ export type EventData = EventDataRegistry[T];