{"_id":"@devx-retailos/gift-voucher","_rev":"7-964e5e1a48ff0178dfdeece9b1deec67","name":"@devx-retailos/gift-voucher","dist-tags":{"latest":"0.0.3"},"versions":{"0.0.1":{"name":"@devx-retailos/gift-voucher","version":"0.0.1","keywords":["medusa-plugin"],"license":"MIT","_id":"@devx-retailos/gift-voucher@0.0.1","maintainers":[{"name":"brijeshagarwal","email":"brijesh@devxlabs.ai"},{"name":"milanghoghari","email":"milan.ghoghari@devxlabs.ai"}],"dist":{"shasum":"13907d51752a4fbf2695d87a8c05704f46e5b81f","tarball":"https://registry.npmjs.org/@devx-retailos/gift-voucher/-/gift-voucher-0.0.1.tgz","fileCount":59,"integrity":"sha512-UwsuQGP6884OR+jDtqnB96nXJXhtaRRf6Bq+u/vbRFqv2gsSqmeYaB0h3PyOW6JkJHAG1SOJCLmWb7204J2z5g==","signatures":[{"sig":"MEYCIQC9K3UJI7FX3ejfIcNJKVkz3SQpCF6A6ARvsZn942wzoQIhAM8be4+NirIO+d7GCpdoxn+PHnmVs1gTaqKtRTmnHgRp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":166506},"main":"./.medusa/server/src/modules/gift-voucher/index.js","_from":"file:devx-retailos-gift-voucher-0.0.1.tgz","types":"./.medusa/server/src/modules/gift-voucher/index.d.ts","exports":{".":{"types":"./.medusa/server/src/modules/gift-voucher/index.d.ts","import":"./.medusa/server/src/modules/gift-voucher/index.js","require":"./.medusa/server/src/modules/gift-voucher/index.js"},"./permissions":{"types":"./.medusa/server/src/modules/gift-voucher/permissions.d.ts","import":"./.medusa/server/src/modules/gift-voucher/permissions.js","require":"./.medusa/server/src/modules/gift-voucher/permissions.js"},"./package.json":"./package.json","./payment-adapter":{"types":"./.medusa/server/src/modules/gift-voucher/payment-adapter/index.d.ts","import":"./.medusa/server/src/modules/gift-voucher/payment-adapter/index.js","require":"./.medusa/server/src/modules/gift-voucher/payment-adapter/index.js"},"./.medusa/server/src/modules/gift-voucher":"./.medusa/server/src/modules/gift-voucher/index.js","./.medusa/server/src/modules/gift-voucher/*":"./.medusa/server/src/modules/gift-voucher/*"},"scripts":{"test":"vitest run","build":"medusa plugin:build","clean":"rm -rf .medusa dist .turbo *.tsbuildinfo","develop":"medusa plugin:develop","typecheck":"tsc --noEmit","db:generate":"medusa plugin:db:generate"},"_npmUser":{"name":"milanghoghari","email":"milan.ghoghari@devxlabs.ai"},"_resolved":"/tmp/ebfe26263affea94d0c81565446778f9/devx-retailos-gift-voucher-0.0.1.tgz","_integrity":"sha512-UwsuQGP6884OR+jDtqnB96nXJXhtaRRf6Bq+u/vbRFqv2gsSqmeYaB0h3PyOW6JkJHAG1SOJCLmWb7204J2z5g==","_npmVersion":"10.8.2","description":"Generic gift voucher module for retailOS: issuance, redemption-as-tender, ledger, expiry, and refund-to-voucher.","directories":{},"sideEffects":false,"_nodeVersion":"20.20.2","dependencies":{"@devx-retailos/core":"0.0.1","@devx-retailos/rbac":"0.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.23.0","vitest":"^2.0.0","typescript":"^5.7.2","@medusajs/cli":"2.15.5","@medusajs/medusa":"2.15.5","@medusajs/admin-sdk":"2.15.5","@medusajs/framework":"2.15.5","@medusajs/admin-shared":"2.15.5"},"peerDependencies":{"@medusajs/medusa":"^2.15.0","@medusajs/framework":"^2.15.0"},"_npmOperationalInternal":{"tmp":"tmp/gift-voucher_0.0.1_1781164524852_0.612731216705082","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@devx-retailos/gift-voucher","version":"0.0.2","keywords":["medusa-plugin"],"license":"MIT","_id":"@devx-retailos/gift-voucher@0.0.2","maintainers":[{"name":"brijeshagarwal","email":"brijesh@devxlabs.ai"},{"name":"milanghoghari","email":"milan.ghoghari@devxlabs.ai"}],"dist":{"shasum":"ccc4688cc3b8a69b72c825120d27c3a2c73d6bb2","tarball":"https://registry.npmjs.org/@devx-retailos/gift-voucher/-/gift-voucher-0.0.2.tgz","fileCount":60,"integrity":"sha512-lTuxn8EYiqCgkmIss5a9axicjphYzmEeZDk3dtMC7vAyrF707yPENv8BM8TTsKtmLEI4olVULwfDx4HK/2jy6Q==","signatures":[{"sig":"MEUCIQCeD8BaQPH/hy8G4CB9+1nQ1vzBd2NQB4zwstUudRO/OgIgMMGIiFEEwPaBopYD7rG+FlsVuAGjEJzH9er0gBVAQqk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":172276},"main":"./.medusa/server/src/modules/gift-voucher/index.js","_from":"file:devx-retailos-gift-voucher-0.0.2.tgz","types":"./.medusa/server/src/modules/gift-voucher/index.d.ts","exports":{".":{"types":"./.medusa/server/src/modules/gift-voucher/index.d.ts","import":"./.medusa/server/src/modules/gift-voucher/index.js","require":"./.medusa/server/src/modules/gift-voucher/index.js"},"./permissions":{"types":"./.medusa/server/src/modules/gift-voucher/permissions.d.ts","import":"./.medusa/server/src/modules/gift-voucher/permissions.js","require":"./.medusa/server/src/modules/gift-voucher/permissions.js"},"./package.json":"./package.json","./payment-adapter":{"types":"./.medusa/server/src/modules/gift-voucher/payment-adapter/index.d.ts","import":"./.medusa/server/src/modules/gift-voucher/payment-adapter/index.js","require":"./.medusa/server/src/modules/gift-voucher/payment-adapter/index.js"},"./.medusa/server/src/modules/gift-voucher":"./.medusa/server/src/modules/gift-voucher/index.js","./.medusa/server/src/modules/gift-voucher/*":"./.medusa/server/src/modules/gift-voucher/*"},"scripts":{"test":"vitest run","build":"medusa plugin:build","clean":"rm -rf .medusa dist .turbo *.tsbuildinfo","develop":"medusa plugin:develop","typecheck":"tsc --noEmit","db:generate":"medusa plugin:db:generate"},"_npmUser":{"name":"milanghoghari","email":"milan.ghoghari@devxlabs.ai"},"_resolved":"/tmp/a9d9b9f0dccdd172a721773fb163329d/devx-retailos-gift-voucher-0.0.2.tgz","_integrity":"sha512-lTuxn8EYiqCgkmIss5a9axicjphYzmEeZDk3dtMC7vAyrF707yPENv8BM8TTsKtmLEI4olVULwfDx4HK/2jy6Q==","_npmVersion":"10.8.2","description":"Generic gift voucher module for retailOS: issuance, redemption-as-tender, ledger, expiry, and refund-to-voucher.","directories":{},"sideEffects":false,"_nodeVersion":"20.20.2","dependencies":{"@devx-retailos/core":"0.0.2","@devx-retailos/rbac":"0.0.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.23.0","vitest":"^2.0.0","typescript":"^5.7.2","@medusajs/cli":"2.15.5","@medusajs/medusa":"2.15.5","@medusajs/admin-sdk":"2.15.5","@medusajs/framework":"2.15.5","@medusajs/admin-shared":"2.15.5"},"peerDependencies":{"@medusajs/medusa":"^2.15.0","@medusajs/framework":"^2.15.0"},"_npmOperationalInternal":{"tmp":"tmp/gift-voucher_0.0.2_1781166329991_0.3022543727282392","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@devx-retailos/gift-voucher","version":"0.0.3","description":"Generic gift voucher module for retailOS: issuance, redemption-as-tender, ledger, expiry, and refund-to-voucher.","license":"MIT","main":"./.medusa/server/src/modules/gift-voucher/index.js","types":"./.medusa/server/src/modules/gift-voucher/index.d.ts","exports":{".":{"types":"./.medusa/server/src/modules/gift-voucher/index.d.ts","import":"./.medusa/server/src/modules/gift-voucher/index.js","require":"./.medusa/server/src/modules/gift-voucher/index.js"},"./permissions":{"types":"./.medusa/server/src/modules/gift-voucher/permissions.d.ts","import":"./.medusa/server/src/modules/gift-voucher/permissions.js","require":"./.medusa/server/src/modules/gift-voucher/permissions.js"},"./payment-adapter":{"types":"./.medusa/server/src/modules/gift-voucher/payment-adapter/index.d.ts","import":"./.medusa/server/src/modules/gift-voucher/payment-adapter/index.js","require":"./.medusa/server/src/modules/gift-voucher/payment-adapter/index.js"},"./package.json":"./package.json","./.medusa/server/src/modules/gift-voucher":"./.medusa/server/src/modules/gift-voucher/index.js","./.medusa/server/src/modules/gift-voucher/*":"./.medusa/server/src/modules/gift-voucher/*"},"dependencies":{"@devx-retailos/core":"0.0.2","@devx-retailos/rbac":"0.1.0"},"peerDependencies":{"@medusajs/framework":"^2.15.0","@medusajs/medusa":"^2.15.0"},"devDependencies":{"@medusajs/admin-sdk":"2.15.5","@medusajs/admin-shared":"2.15.5","@medusajs/cli":"2.15.5","@medusajs/framework":"2.15.5","@medusajs/medusa":"2.15.5","typescript":"^5.7.2","vitest":"^2.0.0","zod":"^3.23.0"},"publishConfig":{"access":"public"},"sideEffects":false,"keywords":["medusa-plugin"],"scripts":{"build":"medusa plugin:build","develop":"medusa plugin:develop","db:generate":"medusa plugin:db:generate","test":"vitest run","typecheck":"tsc --noEmit","clean":"rm -rf .medusa dist .turbo *.tsbuildinfo"},"_id":"@devx-retailos/gift-voucher@0.0.3","_integrity":"sha512-qt3X450NGfTRU6pfvzA8gAD2qnWathzZ/Es6w0D69JxHiltJcGyXCPmCGqsuccA55GmLzgmfqoOKpU3l8/9EbA==","_resolved":"/tmp/0282292f537f62164ffd9e2dd629beb6/devx-retailos-gift-voucher-0.0.3.tgz","_from":"file:devx-retailos-gift-voucher-0.0.3.tgz","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-qt3X450NGfTRU6pfvzA8gAD2qnWathzZ/Es6w0D69JxHiltJcGyXCPmCGqsuccA55GmLzgmfqoOKpU3l8/9EbA==","shasum":"02f5907ccf352fc35bc1cb949cd3c8dbdb874efc","tarball":"https://registry.npmjs.org/@devx-retailos/gift-voucher/-/gift-voucher-0.0.3.tgz","fileCount":60,"unpackedSize":172276,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAuHZ7OhXWSJ2FGO0/bwzyOJ18O0UpVI9fEhc3AVqlGZAiAn/8Yana9Nejzk7Xa+LW7kMujBvduWzHiilUXABhj0Cw=="}]},"_npmUser":{"name":"milanghoghari","email":"milan.ghoghari@devxlabs.ai"},"directories":{},"maintainers":[{"name":"jinangvohera","email":"jinang.vohera@devxlabs.ai"},{"name":"nayan-devx","email":"nayan@devxlabs.ai"},{"name":"kaushal_1717","email":"kaushal.padaliya@devxlabs.ai"},{"name":"karandevx","email":"karan.desai@devxlabs.ai"},{"name":"brijeshagarwal","email":"brijesh@devxlabs.ai"},{"name":"milanghoghari","email":"milan.ghoghari@devxlabs.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gift-voucher_0.0.3_1785407385728_0.8088965114850613"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-11T07:55:24.703Z","modified":"2026-07-30T10:29:46.208Z","0.0.1":"2026-06-11T07:55:25.028Z","0.0.2":"2026-06-11T08:25:30.180Z","0.0.3":"2026-07-30T10:29:45.924Z"},"license":"MIT","keywords":["medusa-plugin"],"description":"Generic gift voucher module for retailOS: issuance, redemption-as-tender, ledger, expiry, and refund-to-voucher.","maintainers":[{"name":"jinangvohera","email":"jinang.vohera@devxlabs.ai"},{"name":"nayan-devx","email":"nayan@devxlabs.ai"},{"name":"kaushal_1717","email":"kaushal.padaliya@devxlabs.ai"},{"name":"karandevx","email":"karan.desai@devxlabs.ai"},{"name":"brijeshagarwal","email":"brijesh@devxlabs.ai"},{"name":"milanghoghari","email":"milan.ghoghari@devxlabs.ai"}],"readme":"# @devx-retailos/gift-voucher\n\nGift voucher module for POS backends: issuance, redemption-as-tender, an append-only transaction ledger, expiry, top-up, void, and refund-to-voucher.\n\nPart of **retailOS**, a Medusa v2 SDK for offline-store POS systems. Packages are installed independently and composed in a brand's Medusa backend.\n\n## Installation\n\n```bash\nnpm install @devx-retailos/gift-voucher\n```\n\nRequires `@medusajs/framework` and `@medusajs/medusa` `^2.15.0` as peer dependencies. Depends on `@devx-retailos/core` and `@devx-retailos/rbac` (vouchers are linked to RBAC organizations and stores, and API routes are permission-guarded).\n\n## Setup\n\n```ts\n// medusa-config.ts\nexport default defineConfig({\n  // ...\n  plugins: [\n    {\n      resolve: \"@devx-retailos/gift-voucher\",\n      options: {},\n    },\n  ],\n})\n```\n\nThe module registers under the `gift_voucher` key (exported as `GIFT_VOUCHER_MODULE`) and registers its permission keys at boot via a module loader.\n\n## Usage\n\n```ts\nimport { GIFT_VOUCHER_MODULE, type GiftVoucherModuleService } from \"@devx-retailos/gift-voucher\"\n\nconst vouchers = container.resolve<GiftVoucherModuleService>(GIFT_VOUCHER_MODULE)\n\n// 1. Issue — generates a unique code, writes an ISSUE ledger entry\nconst voucher = await vouchers.issue({\n  organization_id: \"org_01\",\n  store_id: \"store_01\",\n  currency: \"INR\",\n  initial_balance: 100000,\n  issued_by_employee_id: \"emp_01\",\n  expires_at: new Date(\"2027-01-01\"),\n})\n\n// 2. Check validity and balance before tendering\nconst status = await vouchers.check(voucher.code)\n// → { valid, balance, expires_at, status }\n\n// 3. Redeem as tender at checkout — writes a DEBIT ledger entry\nawait vouchers.debit({ code: voucher.code, amount: 25000, order_id: \"order_01\" })\n\n// 4. Refund back to the voucher — writes a CREDIT ledger entry\nawait vouchers.credit({ voucher_id: voucher.id, amount: 25000, order_id: \"order_01\" })\n\n// Also available: topup(), void(), listTransactions(voucher_id)\n```\n\nVoucher status moves through `ACTIVE` → `PARTIALLY_USED` → `USED`; `VOIDED` is terminal, and `check()` reports `EXPIRED` for past-expiry vouchers. Every balance change is recorded as a `VoucherTxn` (`ISSUE`, `DEBIT`, `CREDIT`, `VOID`, `TOPUP`).\n\n### Redemption as a payment tender\n\n`@devx-retailos/gift-voucher/payment-adapter` exports a factory that produces a `PaymentAdapter` for `@devx-retailos/payments` — it debits the ledger on capture and credits on refund:\n\n```ts\nimport { createVoucherPaymentAdapter } from \"@devx-retailos/gift-voucher/payment-adapter\"\n\nconst adapter = createVoucherPaymentAdapter(vouchers) // GiftVoucherModuleService\npaymentsService.registerAdapter(adapter) // PaymentsModuleService from @devx-retailos/payments\n```\n\nThe adapter's `type` is `\"voucher\"`; its config is `{ voucher_code, voucher_id? }` (`voucher_id` is required for refunds).\n\n## Extension points\n\nVoucher records can be mirrored to an external voucher backend by registering a `VoucherBackendAdapter`. The built-in `internal` adapter (ledger only, no external system) is registered by default:\n\n```ts\nimport type { VoucherBackendAdapter } from \"@devx-retailos/gift-voucher\"\n\nconst externalAdapter: VoucherBackendAdapter<{ api_key: string }> = {\n  type: \"external_provider\",\n  validateConfig(config) {\n    return config as { api_key: string } // typically a zod parse\n  },\n  async issue(config, voucher) {\n    // create the voucher upstream; voucher = { id, code, amount, currency }\n    return { external_id: \"ext_123\" }\n  },\n  async debit(config, external_id, amount, currency) { /* ... */ },\n  async credit(config, external_id, amount, currency) { /* ... */ },\n}\n\nvouchers.registerAdapter(externalAdapter)\n// then: vouchers.issue({ ..., adapter_type: \"external_provider\", adapter_config: { api_key } })\n```\n\n## Permissions\n\nRegistered via `VOUCHER_PERMISSIONS` (subpath `@devx-retailos/gift-voucher/permissions`):\n\n- `voucher.read` — view vouchers and their ledger\n- `voucher.issue` — issue a new gift voucher\n- `voucher.redeem` — redeem (debit) a voucher at checkout\n- `voucher.credit` — credit (refund) an amount back to a voucher\n- `voucher.void` — void a voucher permanently\n- `voucher.report` — view voucher aggregates and export data\n\n## API routes\n\nAll routes are guarded with `requirePermission` from `@devx-retailos/rbac/middlewares`:\n\n| Method | Path | Description | Permission |\n| --- | --- | --- | --- |\n| GET | `/admin/retailos/vouchers` | List vouchers | `voucher.read` |\n| POST | `/admin/retailos/vouchers` | Issue a voucher | `voucher.issue` |\n| GET | `/admin/retailos/vouchers/:id` | Voucher detail + full ledger | `voucher.read` |\n| POST | `/admin/retailos/vouchers/:id/topup` | Add balance to a voucher | `voucher.issue` |\n| POST | `/admin/retailos/vouchers/:id/void` | Void a voucher | `voucher.void` |\n| GET | `/admin/retailos/vouchers/check/:code` | Check validity and balance by code | `voucher.redeem` |\n\n## Errors\n\nAll errors extend `RetailOSError` from `@devx-retailos/core` — switch on `err.code`:\n\n- `RETAILOS_VOUCHER_NOT_FOUND`\n- `RETAILOS_VOUCHER_EXPIRED`\n- `RETAILOS_VOUCHER_INSUFFICIENT_BALANCE` (carries `available` and `requested`)\n- `RETAILOS_VOUCHER_ALREADY_VOIDED`\n- `RETAILOS_VOUCHER_INVALID_STATUS` (carries `status`)\n- `RETAILOS_VOUCHER_CODE_CONFLICT`\n\n## Related packages\n\n- `@devx-retailos/core` — shared types, `Logger`, `RetailOSError`, permission registry\n- `@devx-retailos/rbac` — organizations, stores, roles, permission enforcement\n- `@devx-retailos/payments` — pluggable payment adapters; host for the voucher tender\n- `@devx-retailos/order` — POS orders and payments capture\n- `@devx-retailos/discount` — discount and coupon engine\n- `@devx-retailos/sdk-client` — typed frontend client and React hooks\n\n## License\n\nMIT\n","readmeFilename":"README.md"}