`@withpotter/giftcard` — module reference

HTTP routes this module mounts, plus its internal use-cases, entities, and repositories. The exhaustive request/response contract is the engine’s OpenAPI document at /docs; the layered structure below follows the package internal architecture.

HTTP routes

Gift Cards `/giftcards`

Method	Path	Auth	Description
`GET`	`/giftcards`	Yes	Get all gift cards
`GET`	`/giftcards/:id`	Yes	Get a gift card by ID
`GET`	`/giftcards/stats`	Yes	Get gift card statistics
`POST`	`/giftcards`	Yes	Create a new gift card
`POST`	`/giftcards/check-balance`	—	Check gift card balance by code
`POST`	`/giftcards/code/:code/redeem`	Yes	Redeem a gift card by code
`PUT`	`/giftcards/:id`	Yes	Update a gift card
`DELETE`	`/giftcards/:id`	Yes	Delete a gift card

Internals

Use-cases

Application operations. Each is a single-purpose class with one execute() method.

Use-case	Signature
`CheckGiftCardBalanceUseCase`	`execute(tenantId: string, code: string)`
`CreateGiftCardUseCase`	`execute(tenantId: string, dto: CreateGiftCardDto)`
`DeleteGiftCardUseCase`	`execute(tenantId: string, giftCardId: string)`
`GetGiftCardStatsUseCase`	`execute(tenantId: string)`
`GetGiftCardUseCase`	`execute(tenantId: string, giftCardId: string)`
`ListGiftCardsUseCase`	`execute(tenantId: string, query: ListGiftCardsQuery)`
`RedeemGiftCardUseCase`	`execute(tenantId: string, code: string, amount: number, referenceId?: string, note?: string)`
`UpdateGiftCardUseCase`	`execute(tenantId: string, giftCardId: string, dto: UpdateGiftCardDto)`

Entities

Sequelize models owned by this module.

`GiftCard` — table `gift_cards`

Field	Type
`id`	`string`
`tenantId`	`string`
`tenant`	`Tenant`
`code`	`string`
`originalAmount`	`number`
`balance`	`number`
`currency`	`string`
`recipientEmail`	`string \| null`
`recipientName`	`string \| null`
`personalMessage`	`string \| null`
`purchaserEmail`	`string \| null`
`purchaserName`	`string \| null`
`orderId`	`string \| null`
`status`	`GiftCardStatus`
`expiresAt`	`Date \| null`
`activatedAt`	`Date \| null`
`lastUsedAt`	`Date \| null`
`redemptions`	`GiftCardRedemption[]`
`emailSent`	`boolean`
`emailSentAt`	`Date \| null`
`scheduledDeliveryDate`	`Date \| null`
`createdAt`	`Date`
`updatedAt`	`Date`

Repositories

Data-access classes wrapping the entities.

`GiftCardRepository`

createForTenant · findByTenant · findByCode · findAllForTenant · updateForTenant · deleteForTenant · redeem · checkBalance · getStats · findPendingDelivery · markEmailSent

Generated from the module’s source. Routes are relative to the engine root (default http://localhost:3001). For full request/response schemas use the live OpenAPI document.

gallery inquiry

@withpotter/giftcard — module reference