{"_id":"@biorbank/moon-sdk","_rev":"5-88696ee89ad154f88cf962e11f582c5e","name":"@biorbank/moon-sdk","dist-tags":{"latest":"0.1.6"},"versions":{"0.1.1":{"name":"@biorbank/moon-sdk","version":"0.1.1","keywords":["moon","card-issuing","api","sdk","typescript","payments","crypto","cards"],"author":{"name":"Moon SDK Team"},"license":"MIT","_id":"@biorbank/moon-sdk@0.1.1","maintainers":[{"name":"keithagroves","email":"keithalgroves@gmail.com"}],"homepage":"https://github.com/paywithmoon/typescript-sdk#readme","bugs":{"url":"https://github.com/paywithmoon/typescript-sdk/issues"},"dist":{"shasum":"16fd2e7f42ff4ad01d71c9f3596b9d038cc92d1e","tarball":"https://registry.npmjs.org/@biorbank/moon-sdk/-/moon-sdk-0.1.1.tgz","fileCount":8,"integrity":"sha512-TnxGk6vts0yb+kgCgYmZ6R0LIRhOx0mE728iRUBueIAGQUCf6tss9ApCb3XbwL017IiDo0UX6Qg4671KaBtxXw==","signatures":[{"sig":"MEUCIQDga04nYQ8OhNdXmEkQP7QtWwxVBvAn4KMRsDO6XJOGvgIgMPiJZBmeMCT1cb0sbjAF+fc7VVOT4IEGEhhDhpWQfoM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":878750},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16"},"gitHead":"bdbbe798b265e81a88c4a34b65109cf2a45da432","private":false,"scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"jest","build":"tsup","setup":"npm run setup:env && npm run setup:webhook-secret","format":"prettier --write src","setup:env":"cp .env.example .env && echo '✅ Created .env file - please edit with your actual values'","test:watch":"jest --watch","type-check":"tsc --noEmit","example:basic":"npm run build && node dist/examples/basic-usage.js","security:docs":"echo '📖 Security documentation: ./SECURITY.md'","example:secure":"npm run build && node dist/examples/secure-integration.js","generate-types":"node scripts/generate-types.js","prepublishOnly":"npm run build","security:check":"npm run type-check && echo '✅ Security type checks passed'","example:webhooks":"npm run build && node dist/examples/webhook-management.js","example:gift-cards":"npm run build && node dist/examples/gift-card-management.js","setup:webhook-secret":"node -e \"console.log('\\n🔐 Generated webhook secret:\\n' + require('crypto').randomBytes(32).toString('hex') + '\\n\\nAdd this to your .env file as MOON_WEBHOOK_SECRET')\""},"_npmUser":{"name":"keithagroves","email":"keithalgroves@gmail.com"},"repository":{"url":"git+https://github.com/paywithmoon/typescript-sdk.git","type":"git"},"_npmVersion":"10.9.2","description":"TypeScript SDK for Moon's Card Issuing API","directories":{},"_nodeVersion":"22.17.0","dependencies":{"axios":"^1.11.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.5","tsup":"^8.5.0","eslint":"^9.33.0","ts-jest":"^29.4.1","prettier":"^3.6.2","typescript":"^5.9.2","@types/jest":"^30.0.0","@types/node":"^24.2.1","@typescript-eslint/parser":"^8.39.0","@typescript-eslint/eslint-plugin":"^8.39.0"},"_npmOperationalInternal":{"tmp":"tmp/moon-sdk_0.1.1_1757473993109_0.6399527109231489","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@biorbank/moon-sdk","version":"0.1.2","keywords":["moon","card-issuing","api","sdk","typescript","payments","crypto","cards"],"author":{"name":"Moon SDK Team"},"license":"MIT","_id":"@biorbank/moon-sdk@0.1.2","maintainers":[{"name":"keithagroves","email":"keithalgroves@gmail.com"}],"homepage":"https://github.com/paywithmoon/typescript-sdk#readme","bugs":{"url":"https://github.com/paywithmoon/typescript-sdk/issues"},"dist":{"shasum":"55393df7c025c2d196642dee571690d3762d6402","tarball":"https://registry.npmjs.org/@biorbank/moon-sdk/-/moon-sdk-0.1.2.tgz","fileCount":8,"integrity":"sha512-XtGmhNItiFvemK4s4z/IHOUZtrPE7WHzajXZH3AyK5HSHeU4BZCn4f+EVt6aH07YLOEiziFd+JrmZQO4jtBA/A==","signatures":[{"sig":"MEYCIQCG3lMCEDII0//fneW6FH2NhqZw3fmqMBmzGbY4SXechwIhANW3PHqM2JenbUCm3PAqL1wbdaOnVudmIZHiusuigJdi","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":929696},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16"},"gitHead":"830d6a348b5f3fa19b4834f6879c8c8abd20db87","private":false,"scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"jest","build":"tsup","setup":"npm run setup:env && npm run setup:webhook-secret","format":"prettier --write src","setup:env":"cp .env.example .env && echo '✅ Created .env file - please edit with your actual values'","test:watch":"jest --watch","type-check":"tsc --noEmit","example:cvv":"npm run build && node dist/examples/cvv-access-example.js","example:basic":"npm run build && node dist/examples/basic-usage.js","security:docs":"echo '📖 Security documentation: ./SECURITY.md'","example:secure":"npm run build && node dist/examples/secure-integration.js","generate-types":"node scripts/generate-types.js","prepublishOnly":"npm run build","security:check":"npm run type-check && echo '✅ Security type checks passed'","example:webhooks":"npm run build && node dist/examples/webhook-management.js","example:sensitive":"npm run build && node dist/examples/sensitive-data-access-example.js","example:gift-cards":"npm run build && node dist/examples/gift-card-management.js","setup:webhook-secret":"node -e \"console.log('\\n🔐 Generated webhook secret:\\n' + require('crypto').randomBytes(32).toString('hex') + '\\n\\nAdd this to your .env file as MOON_WEBHOOK_SECRET')\""},"_npmUser":{"name":"keithagroves","email":"keithalgroves@gmail.com"},"repository":{"url":"git+https://github.com/paywithmoon/typescript-sdk.git","type":"git"},"_npmVersion":"10.9.2","description":"TypeScript SDK for Moon's Card Issuing API","directories":{},"_nodeVersion":"22.17.0","dependencies":{"axios":"^1.11.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.5","tsup":"^8.5.0","eslint":"^9.33.0","ts-jest":"^29.4.1","prettier":"^3.6.2","typescript":"^5.9.2","@types/jest":"^30.0.0","@types/node":"^24.2.1","@typescript-eslint/parser":"^8.39.0","@typescript-eslint/eslint-plugin":"^8.39.0"},"_npmOperationalInternal":{"tmp":"tmp/moon-sdk_0.1.2_1757781184682_0.20704441652636607","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@biorbank/moon-sdk","version":"0.1.4","keywords":["moon","card-issuing","api","sdk","typescript","payments","crypto","cards"],"author":{"name":"Moon SDK Team"},"license":"MIT","_id":"@biorbank/moon-sdk@0.1.4","maintainers":[{"name":"keithagroves","email":"keithalgroves@gmail.com"}],"homepage":"https://github.com/paywithmoon/typescript-sdk#readme","bugs":{"url":"https://github.com/paywithmoon/typescript-sdk/issues"},"dist":{"shasum":"bfd8bfb83a490e496b1ae763b0cd08593086d85d","tarball":"https://registry.npmjs.org/@biorbank/moon-sdk/-/moon-sdk-0.1.4.tgz","fileCount":8,"integrity":"sha512-4tVDOf4o+ylNw9cQkID6hG8OqMa8sk7cYShVVJamwW7CUROR2H9f5FJvm7FzXQbPGcXFjiOsh1YFO7lQlbH+0w==","signatures":[{"sig":"MEUCIQDaoewlRsPV8WWYUZNQJJzAnjbXp1P73wfapFKqngHe4gIgUzPvG3cNmfSAcrz1ey981lsFxI6YxII/5e3JgcCoZzg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":938496},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16"},"gitHead":"23b4c392cb79b1d3d18bedf422cde03a7bcd285e","private":false,"scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"jest","build":"tsup","setup":"npm run setup:env && npm run setup:webhook-secret","format":"prettier --write src","setup:env":"cp .env.example .env && echo '✅ Created .env file - please edit with your actual values'","test:watch":"jest --watch","type-check":"tsc --noEmit","example:cvv":"npm run build && node dist/examples/cvv-access-example.js","example:basic":"npm run build && node dist/examples/basic-usage.js","security:docs":"echo '📖 Security documentation: ./SECURITY.md'","example:secure":"npm run build && node dist/examples/secure-integration.js","generate-types":"node scripts/generate-types.js","prepublishOnly":"npm run build","security:check":"npm run type-check && echo '✅ Security type checks passed'","example:webhooks":"npm run build && node dist/examples/webhook-management.js","example:sensitive":"npm run build && node dist/examples/sensitive-data-access-example.js","example:gift-cards":"npm run build && node dist/examples/gift-card-management.js","setup:webhook-secret":"node -e \"console.log('\\n🔐 Generated webhook secret:\\n' + require('crypto').randomBytes(32).toString('hex') + '\\n\\nAdd this to your .env file as MOON_WEBHOOK_SECRET')\""},"_npmUser":{"name":"keithagroves","email":"keithalgroves@gmail.com"},"repository":{"url":"git+https://github.com/paywithmoon/typescript-sdk.git","type":"git"},"_npmVersion":"10.9.2","description":"TypeScript SDK for Moon's Card Issuing API","directories":{},"_nodeVersion":"22.17.0","dependencies":{"axios":"^1.11.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.5","tsup":"^8.5.0","eslint":"^9.33.0","ts-jest":"^29.4.1","prettier":"^3.6.2","typescript":"^5.9.2","@types/jest":"^30.0.0","@types/node":"^24.2.1","@typescript-eslint/parser":"^8.39.0","@typescript-eslint/eslint-plugin":"^8.39.0"},"_npmOperationalInternal":{"tmp":"tmp/moon-sdk_0.1.4_1757795337209_0.8119153246461346","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@biorbank/moon-sdk","version":"0.1.5","keywords":["moon","card-issuing","api","sdk","typescript","payments","crypto","cards"],"author":{"name":"Moon SDK Team"},"license":"MIT","_id":"@biorbank/moon-sdk@0.1.5","maintainers":[{"name":"keithagroves","email":"keithalgroves@gmail.com"}],"homepage":"https://github.com/paywithmoon/typescript-sdk#readme","bugs":{"url":"https://github.com/paywithmoon/typescript-sdk/issues"},"dist":{"shasum":"3be95558ad6ea1276086e0b7332212e791392ea4","tarball":"https://registry.npmjs.org/@biorbank/moon-sdk/-/moon-sdk-0.1.5.tgz","fileCount":8,"integrity":"sha512-osnTbOq2m0zbpMVhAfB+MyneqfRn5oSNPb3LQPlmUy1oJhFoMqvFSX++Km8Gmjp/eLBRkj5D/TpeEhG0me9dzA==","signatures":[{"sig":"MEYCIQDPPCM2HQpwmMw1LBPdP3H3PWY5Ys5kmNBFIVS2qTnfCgIhAJF1bcUlrJKAUnRO8cD70RE1IINw3a8UYezyP8/sa8pI","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":942836},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16"},"gitHead":"036f433e4eb22594c00520061115e96d6b36cd0d","private":false,"scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"jest","build":"tsup","setup":"npm run setup:env && npm run setup:webhook-secret","format":"prettier --write src","setup:env":"cp .env.example .env && echo '✅ Created .env file - please edit with your actual values'","test:watch":"jest --watch","type-check":"tsc --noEmit","example:cvv":"npm run build && node dist/examples/cvv-access-example.js","example:basic":"npm run build && node dist/examples/basic-usage.js","security:docs":"echo '📖 Security documentation: ./SECURITY.md'","example:secure":"npm run build && node dist/examples/secure-integration.js","generate-types":"node scripts/generate-types.js","prepublishOnly":"npm run build","security:check":"npm run type-check && echo '✅ Security type checks passed'","example:webhooks":"npm run build && node dist/examples/webhook-management.js","example:sensitive":"npm run build && node dist/examples/sensitive-data-access-example.js","example:gift-cards":"npm run build && node dist/examples/gift-card-management.js","setup:webhook-secret":"node -e \"console.log('\\n🔐 Generated webhook secret:\\n' + require('crypto').randomBytes(32).toString('hex') + '\\n\\nAdd this to your .env file as MOON_WEBHOOK_SECRET')\""},"_npmUser":{"name":"keithagroves","email":"keithalgroves@gmail.com"},"repository":{"url":"git+https://github.com/paywithmoon/typescript-sdk.git","type":"git"},"_npmVersion":"10.9.2","description":"TypeScript SDK for Moon's Card Issuing API","directories":{},"_nodeVersion":"22.17.0","dependencies":{"axios":"^1.11.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.5","tsup":"^8.5.0","eslint":"^9.33.0","ts-jest":"^29.4.1","prettier":"^3.6.2","typescript":"^5.9.2","@types/jest":"^30.0.0","@types/node":"^24.2.1","@typescript-eslint/parser":"^8.39.0","@typescript-eslint/eslint-plugin":"^8.39.0"},"_npmOperationalInternal":{"tmp":"tmp/moon-sdk_0.1.5_1757799592952_0.32116180174287434","host":"s3://npm-registry-packages-npm-production"}},"0.1.6":{"name":"@biorbank/moon-sdk","version":"0.1.6","description":"TypeScript SDK for Moon's Card Issuing API","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","private":false,"scripts":{"build":"tsup","dev":"tsup --watch","test":"jest","test:watch":"jest --watch","type-check":"tsc --noEmit","lint":"eslint src --ext .ts","format":"prettier --write src","generate-types":"node scripts/generate-types.js","prepublishOnly":"npm run build","setup":"npm run setup:env && npm run setup:webhook-secret","setup:env":"cp .env.example .env && echo '✅ Created .env file - please edit with your actual values'","setup:webhook-secret":"node -e \"console.log('\\n🔐 Generated webhook secret:\\n' + require('crypto').randomBytes(32).toString('hex') + '\\n\\nAdd this to your .env file as MOON_WEBHOOK_SECRET')\"","example:basic":"npm run build && node dist/examples/basic-usage.js","example:secure":"npm run build && node dist/examples/secure-integration.js","example:webhooks":"npm run build && node dist/examples/webhook-management.js","example:gift-cards":"npm run build && node dist/examples/gift-card-management.js","example:cvv":"npm run build && node dist/examples/cvv-access-example.js","example:sensitive":"npm run build && node dist/examples/sensitive-data-access-example.js","verify:sensitive-fix":"npm run build && node scripts/verify-sensitive-data-fix.js","security:check":"npm run type-check && echo '✅ Security type checks passed'","security:docs":"echo '📖 Security documentation: ./SECURITY.md'"},"keywords":["moon","card-issuing","api","sdk","typescript","payments","crypto","cards"],"author":{"name":"Moon SDK Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/paywithmoon/typescript-sdk.git"},"dependencies":{"axios":"^1.11.0"},"devDependencies":{"@types/jest":"^30.0.0","@types/node":"^24.2.1","@typescript-eslint/eslint-plugin":"^8.39.0","@typescript-eslint/parser":"^8.39.0","eslint":"^9.33.0","jest":"^30.0.5","prettier":"^3.6.2","ts-jest":"^29.4.1","tsup":"^8.5.0","typescript":"^5.9.2"},"engines":{"node":">=16"},"_id":"@biorbank/moon-sdk@0.1.6","gitHead":"7c53cda57cc3eac3542e611a30594c1584b0b218","bugs":{"url":"https://github.com/paywithmoon/typescript-sdk/issues"},"homepage":"https://github.com/paywithmoon/typescript-sdk#readme","_nodeVersion":"22.17.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-3JjFakuxOIu9c20eDJBbqVrYqcunwpIgbQSV/PbG77C4SAUsd+dvhAQH3GHaHYPtDsb+O5hsbAqxcbJadhvPbA==","shasum":"a893e3c9c9b1ee583ab667fc5a3fdd7ead74a361","tarball":"https://registry.npmjs.org/@biorbank/moon-sdk/-/moon-sdk-0.1.6.tgz","fileCount":8,"unpackedSize":1120638,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCrakaELVZg4NL1Uck5oElcSPTM0AQW214FOzFAktgRqAIgcCFsaNPrxFmQD04Qgef54sdgXI9qRF8EEvRtkgORjkw="}]},"_npmUser":{"name":"keithagroves","email":"keithalgroves@gmail.com"},"directories":{},"maintainers":[{"name":"keithagroves","email":"keithalgroves@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/moon-sdk_0.1.6_1757801513474_0.05032699316627354"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-10T03:13:13.005Z","modified":"2025-09-13T22:11:53.914Z","0.1.1":"2025-09-10T03:13:13.374Z","0.1.2":"2025-09-13T16:33:04.907Z","0.1.4":"2025-09-13T20:28:57.480Z","0.1.5":"2025-09-13T21:39:53.193Z","0.1.6":"2025-09-13T22:11:53.710Z"},"bugs":{"url":"https://github.com/paywithmoon/typescript-sdk/issues"},"author":{"name":"Moon SDK Team"},"license":"MIT","homepage":"https://github.com/paywithmoon/typescript-sdk#readme","keywords":["moon","card-issuing","api","sdk","typescript","payments","crypto","cards"],"repository":{"type":"git","url":"git+https://github.com/paywithmoon/typescript-sdk.git"},"description":"TypeScript SDK for Moon's Card Issuing API","maintainers":[{"name":"keithagroves","email":"keithalgroves@gmail.com"}],"readme":"# Moon Card Issuing SDK for TypeScript\n\nA comprehensive TypeScript SDK for Moon's Card Issuing API, providing type-safe access to card management, transaction processing, and crypto funding capabilities.\n\n## Features\n\n- 🔒 **Type Safe** - Full TypeScript support with auto-generated types\n- 🏗️ **Modular** - Clean resource-based architecture  \n- ⚡ **Modern** - Built with async/await and ES modules\n- 🛡️ **Robust** - Comprehensive error handling and retries\n- 🔄 **Auto Retry** - Smart retry logic for transient failures\n- 📖 **Well Documented** - Complete JSDoc documentation\n- 🛡️ **PCI DSS Compliant** - Automatic card data masking and secure handling\n- 🔐 **Webhook Security** - HMAC signature validation and replay protection\n- ⚡ **JIT Authorization** - Sub-second response with rate limiting\n- 🔑 **API Key Management** - Rotation tracking and security monitoring\n- 📋 **Secure Logging** - Environment-aware sensitive data filtering\n- 🔍 **Audit Framework** - Comprehensive security event tracking\n- 🔓 **Sensitive Data Access** - Controlled access to unredacted card data for legitimate business use\n\n## ⚠️ Important: Sensitive Data Access\n\n**Version 0.1.4+** includes fixed sensitive data access methods that properly return unredacted card data:\n\n- `getUnredactedPAN()` - Returns actual PAN (not masked)\n- `getUnredactedCVV()` - Returns actual CVV (not redacted)  \n- `getUnredactedPIN()` - Returns actual PIN (not masked)\n- `getAllSensitiveData()` - Returns all unredacted data\n\nThese methods now **bypass automatic sanitization** and return the raw data from the Moon API as intended. Use with extreme caution and proper authorization controls.\n\n## Installation\n\n```bash\nnpm install moon-card-issuing-sdk\n# or\nyarn add moon-card-issuing-sdk\n```\n\n## Setup\n\n### Quick Setup (Recommended)\n\nUse our automated setup script to get started quickly:\n\n```bash\n# Create .env file and generate secure webhook secret\nnpm run setup\n\n# This will:\n# 1. Copy .env.example to .env\n# 2. Generate a cryptographically secure webhook secret\n# 3. Show you what values to edit\n```\n\n### Manual Setup\n\n#### 1. Environment Configuration\n\nCopy the example environment file and configure your settings:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your actual values:\n\n```bash\n# Required: Your Moon API key\nMOON_API_KEY=your_actual_moon_api_key_here\n\n# Required for webhooks: Secure webhook secret (16+ characters)\nMOON_WEBHOOK_SECRET=your_cryptographically_secure_webhook_secret\n\n# Environment (staging or production)\nNODE_ENV=staging\n```\n\n#### 2. Generate Secure Webhook Secret\n\nFor webhook security, generate a cryptographically secure secret:\n\n```bash\n# Use our built-in generator\nnpm run setup:webhook-secret\n\n# Or generate manually with OpenSSL\nopenssl rand -hex 32\n\n# Or use Node.js\nnode -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"\n```\n\n#### 3. API Key Security\n\n- **Staging**: Use test API keys (may start with `pk_test_`)\n- **Production**: Use live API keys (may start with `pk_live_`)\n- **Never**: Commit API keys to version control\n- **Rotate**: Change keys regularly (monthly recommended)\n\n#### 4. Run Security Checks\n\nValidate your setup with security checks:\n\n```bash\n# Run type checking and security validation\nnpm run security:check\n\n# View security documentation\nnpm run security:docs\n```\n\n## Quick Start\n\n```typescript\nimport { MoonClient } from 'moon-card-issuing-sdk';\n\nconst moon = new MoonClient({\n  apiKey: 'your-api-key',\n  environment: 'staging' // or 'production'\n});\n\n// Create a card\nconst card = await moon.cards.create('card-product-id', {\n  amount: 100,\n  card_type: 'VIRTUAL'\n});\n\n// Add balance\nawait moon.cards.addBalance(card.id, 50);\n\n// Get transactions\nconst transactions = await moon.cards.getTransactions(card.id);\n```\n\n## Configuration\n\n### Client Options\n\n```typescript\nconst moon = new MoonClient({\n  apiKey: 'your-api-key',           // Required: Your Moon API key\n  environment: 'staging',           // 'staging' | 'production' \n  baseURL: 'custom-url',           // Optional: Override base URL\n  timeout: 30000,                  // Optional: Request timeout (ms)\n  retryOptions: {                  // Optional: Retry configuration\n    retries: 3,\n    retryDelay: 1000,\n    retryCondition: (error) => true\n  }\n});\n```\n\n### Environment URLs\n\n- **Staging**: `https://stagingapi.paywithmoon.com`\n- **Production**: `https://api.paywithmoon.com`\n\n## API Reference\n\n### Cards Resource\n\n#### Create Card\n```typescript\nconst card = await moon.cards.create(cardProductId, {\n  amount?: number,\n  card_type?: 'VIRTUAL' | 'PHYSICAL',\n  card_currency?: 'USD' | 'MXN',\n  end_customer_id?: string\n});\n```\n\n#### Get Card\n```typescript\nconst card = await moon.cards.get(cardId);\n```\n\n#### List Cards\n```typescript\nconst cards = await moon.cards.list({\n  currentPage: 1,\n  perPage: 10,\n  end_customer_id?: string,\n  include_inactive_cards?: boolean\n});\n```\n\n#### Add Balance\n```typescript\nconst updatedCard = await moon.cards.addBalance(cardId, amount);\n```\n\n#### Card Management\n```typescript\n// Freeze/unfreeze\nawait moon.cards.freeze(cardId, true);  // freeze\nawait moon.cards.freeze(cardId, false); // unfreeze\n\n// Activate\nawait moon.cards.activate(cardId);\n\n// PIN management\nconst pin = await moon.cards.getPin(cardId);\nawait moon.cards.updatePin(cardId, '1234');\n\n// CVV access (always redacted for PCI DSS compliance)\nconst cvv = await moon.cards.getCvv(cardId); // Returns { cvv: \"***\" }\n\n// ⚠️ SENSITIVE DATA ACCESS - Use with extreme caution!\n// These methods return UNREDACTED sensitive data for legitimate business use\n// All access is heavily logged and monitored\n\n// Get actual PAN (unredacted)\nconst { pan } = await moon.cards.getUnredactedPAN(cardId); // Returns actual PAN\n\n// Get actual CVV (unredacted) \nconst { cvv } = await moon.cards.getUnredactedCVV(cardId); // Returns actual CVV\n\n// Get actual PIN (unredacted)\nconst { pin } = await moon.cards.getUnredactedPIN(cardId); // Returns actual PIN\n\n// Get all sensitive data at once (maximum security risk)\nconst sensitiveData = await moon.cards.getAllSensitiveData(cardId);\n// Returns: { pan, cvv, pin, expiration, display_expiration, support_token }\n\n// Assign cardholder\nawait moon.cards.assignCardholder(cardId, externalId);\n```\n\n#### Transactions\n```typescript\n// Get transactions\nconst transactions = await moon.cards.getTransactions(cardId, {\n  currentPage: 1,\n  perPage: 20\n});\n\n// Simulate transaction (sandbox only)\nawait moon.cards.simulateTransaction(cardId, {\n  transactionAmount: 25.00,\n  transactionCurrency: 'USD',\n  transactionType: 'AUTHORIZATION',\n  merchantName: 'Test Store',\n  merchantCountryCode: 'US'\n});\n```\n\n#### Card Products\n```typescript\nconst products = await moon.cards.getCardProducts({\n  currentPage: 1,\n  perPage: 10\n});\n```\n\n### Webhooks Resource\n\n#### Register Webhook\n```typescript\n// Register a webhook endpoint\nawait moon.webhooks.register({\n  url: 'https://your-app.com/webhooks/moon'\n});\n\n// Validate webhook URL before registration\nconst validation = moon.webhooks.validateWebhookUrl('https://your-app.com/webhooks/moon');\nif (!validation.isValid) {\n  console.error('Invalid webhook URL:', validation.error);\n}\n```\n\n#### Delete Webhook\n```typescript\n// Delete registered webhook\nawait moon.webhooks.delete();\n```\n\n#### Complete Webhook Integration\n```typescript\nimport { MoonClient, createWebhookMiddleware, createWebhookConfig } from 'moon-card-issuing-sdk';\nimport express from 'express';\n\nconst moon = new MoonClient({\n  apiKey: 'your-api-key',\n  environment: 'staging'\n});\n\nconst app = express();\n\n// 1. Register webhook endpoint\nawait moon.webhooks.register({\n  url: 'https://your-app.com/webhooks/moon'\n});\n\n// 2. Set up webhook handler with security validation\nconst config = createWebhookConfig(process.env.MOON_WEBHOOK_SECRET!);\n\napp.post('/webhooks/moon', \n  createWebhookMiddleware(config, async (payload) => {\n    console.log('Secure webhook received:', payload.type);\n    \n    // Handle different event types\n    switch (payload.type) {\n      case 'CARD_TRANSACTION':\n        // Handle card transaction\n        break;\n      case 'CARD_DECLINE':\n        // Handle declined transaction\n        break;\n      case 'MOON_CREDIT_FUNDS_CREDITED':\n        // Handle funds credited\n        break;\n    }\n  })\n);\n```\n\n### Gift Cards Resource\n\n#### Purchase Gift Card\n```typescript\n// Purchase a gift card\nconst giftCard = await moon.giftCards.purchase({\n  card_product_id: 'product-id',\n  amount: '50.00'\n});\n\n// Validate purchase amount before buying\nconst product = await moon.giftCards.getProducts();\nconst validation = moon.giftCards.validatePurchaseAmount(product.data[0], 50);\nif (!validation.isValid) {\n  console.error('Invalid amount:', validation.error);\n}\n```\n\n#### Get Gift Card Details\n```typescript\n// Get gift card by ID (returns masked sensitive data)\nconst giftCard = await moon.giftCards.get('gift-card-id');\nconsole.log('Gift card value:', giftCard.value);\nconsole.log('Barcode:', giftCard.barcode);\n// PIN and security code are masked for security: \"***\"\n```\n\n#### Manage Gift Card Usage\n```typescript\n// Mark as used\nawait moon.giftCards.markAsUsed('gift-card-id');\n\n// Mark as unused\nawait moon.giftCards.markAsUnused('gift-card-id');\n\n// Custom usage status\nawait moon.giftCards.updateUsageStatus('gift-card-id', {\n  marked_used: true\n});\n```\n\n#### Browse Gift Card Products\n```typescript\n// Get all available products\nconst products = await moon.giftCards.getProducts({\n  currentPage: 1,\n  perPage: 10\n});\n\n// Filter by category\nconst retailProducts = await moon.giftCards.getProductsByCategory('retail');\n\n// Filter by merchant\nconst amazonCards = await moon.giftCards.getProductsByMerchant('Amazon');\n```\n\n#### Calculate Costs\n```typescript\n// Calculate total cost including fees and discounts\nconst product = products.data[0];\nconst calculation = moon.giftCards.calculateTotalCost(product, 100);\n\nconsole.log('Gift card amount:', calculation.giftCardAmount);\nconsole.log('Fee amount:', calculation.feeAmount);\nconsole.log('Total cost:', calculation.totalCost);\nconsole.log('Final amount (after discount):', calculation.finalAmount);\n```\n\n### Cardholders Resource\n\n#### Create and Manage Cardholders\n```typescript\n// Create a new cardholder\nconst cardholder = await moon.cardholders.create({\n  email: 'user@company.com',\n  external_id: 'EMP-12345',\n  organization_id: 'org-id'\n});\n\n// Get cardholder by ID\nconst cardholder = await moon.cardholders.get('cardholder-id');\n\n// Update cardholder information\nconst updatedCardholder = await moon.cardholders.update('cardholder-id', {\n  external_id: 'NEW-EMP-67890'\n});\n```\n\n#### List and Search Cardholders\n```typescript\n// List all cardholders with pagination\nconst cardholders = await moon.cardholders.list({\n  currentPage: 1,\n  perPage: 10,\n  organization_id: 'org-id'\n});\n\n// Find cardholders by external ID\nconst found = await moon.cardholders.findByExternalId('EMP-12345');\n\n// Find cardholders by email\nconst byEmail = await moon.cardholders.findByEmail('user@company.com');\n```\n\n#### Two-Factor Authentication\n```typescript\n// Step 1: Request login code\nawait moon.cardholders.requestLoginCode({\n  email: 'user@company.com',\n  organization_id: 'org-id'\n});\n\n// Step 2: Redeem code for token\nconst session = await moon.cardholders.redeemLoginCode({\n  email: 'user@company.com',\n  code: '123456',\n  organization_id: 'org-id'\n});\n\n// Use the JWT token for authenticated requests\nconsole.log('Token:', session.token);\nconsole.log('Expires:', session.expiresAt);\n\n// Complete authentication flow with convenience method\nconst auth = await moon.cardholders.authenticate(\n  'user@company.com',\n  'org-id',\n  async () => {\n    // This function should prompt user for the 6-digit code\n    // and return it (e.g., from a form input)\n    return prompt('Enter the 6-digit code from your email:') || '';\n  }\n);\n```\n\n#### Cardholder-Card Associations\n```typescript\n// Get all cards for a cardholder\nconst cards = await moon.cardholders.getCards('cardholder-id', {\n  currentPage: 1,\n  perPage: 10,\n  include_inactive_cards: false\n});\n\n// Check if cardholder has active cards\nconst hasCards = await moon.cardholders.hasActiveCards('cardholder-id');\n\n// Get total card count\nconst cardCount = await moon.cardholders.getCardCount('cardholder-id', true);\n```\n\n#### Utility Methods\n```typescript\n// Update external ID\nawait moon.cardholders.updateExternalId('cardholder-id', 'NEW-ID-123');\n\n// Move to different organization\nawait moon.cardholders.moveToOrganization('cardholder-id', 'new-org-id');\n\n// Update KYC status\nawait moon.cardholders.updateKYCStatus('cardholder-id', true);\n```\n\n## Error Handling\n\nThe SDK provides specific error types for different scenarios:\n\n```typescript\nimport { \n  MoonError, \n  MoonAPIError, \n  MoonNetworkError,\n  MoonValidationError,\n  MoonRateLimitError,\n  MoonAuthenticationError,\n  MoonNotFoundError\n} from 'moon-card-issuing-sdk';\n\ntry {\n  const card = await moon.cards.get('invalid-id');\n} catch (error) {\n  if (error instanceof MoonNotFoundError) {\n    console.log('Card not found');\n  } else if (error instanceof MoonAuthenticationError) {\n    console.log('Invalid API key');\n  } else if (error instanceof MoonRateLimitError) {\n    console.log('Rate limited, retry after:', error.retryAfter);\n  } else if (error instanceof MoonAPIError) {\n    console.log('API error:', error.status, error.message);\n  }\n}\n```\n\n## TypeScript Support\n\nThe SDK is fully typed with auto-generated interfaces:\n\n```typescript\nimport { Card, Transaction, CardProduct } from 'moon-card-issuing-sdk';\n\n// All responses are properly typed\nconst card: Card = await moon.cards.get('card-id');\nconst transactions: PaginatedResponse<Transaction> = await moon.cards.getTransactions('card-id');\n```\n\n## Pagination\n\nList methods return paginated responses:\n\n```typescript\ninterface PaginatedResponse<T> {\n  data: T[];\n  pagination: {\n    currentPage: number;\n    from: number;\n    lastPage: number;\n    perPage: number;\n    total: number;\n  };\n}\n```\n\n## Development\n\n### Building\n\n```bash\nnpm run build          # Build for production\nnpm run dev           # Build in watch mode\n```\n\n### Testing\n\n```bash\nnpm test              # Run tests\nnpm run test:watch    # Run tests in watch mode\n```\n\n### Type Generation\n\n```bash\nnpm run generate-types # Regenerate types from API schemas\n```\n\n## Examples\n\nCheck the [examples](./examples) directory for complete usage examples:\n\n- [Basic Usage](./examples/basic-usage.ts) - Card creation and management with PCI DSS compliance\n- [Secure Integration](./examples/secure-integration.ts) - Complete security implementation\n- [Webhook Management](./examples/webhook-management.ts) - Secure webhook integration\n- [Gift Card Management](./examples/gift-card-management.ts) - Complete gift card lifecycle\n- [CVV Access](./examples/cvv-access-example.ts) - Secure CVV retrieval with audit logging\n- [Sensitive Data Access](./examples/sensitive-data-access-example.ts) - Unredacted sensitive data access with security controls\n\n### Running Examples\n\nUse the built-in npm scripts to run examples easily:\n\n```bash\n# Run basic card management example\nnpm run example:basic\n\n# Run complete security integration example (includes webhook server)\nnpm run example:secure\n\n# Run webhook management example\nnpm run example:webhooks\n\n# Run gift card management example\nnpm run example:gift-cards\n\n# Run CVV access example with security compliance\nnpm run example:cvv\n\n# Run sensitive data access example (⚠️ UNREDACTED data)\nnpm run example:sensitive\n```\n\nMake sure to configure your `.env` file first with:\n```bash\nnpm run setup\n```\n\n## 🛡️ Security Features\n\nThis SDK implements comprehensive security measures for production use:\n\n### PCI DSS Compliance\n- **Default Security**: Automatic card data masking (PAN shows only last 4 digits)\n- **CVV Protection**: CVV always redacted in standard responses\n- **PIN Protection**: PIN never shown in production environment\n- **Secure Logging**: No sensitive data in standard logs\n\n### ⚠️ Sensitive Data Access\nFor legitimate business operations, the SDK provides secure access to unredacted sensitive data:\n\n#### Standard (Secure) Methods\n```typescript\n// These methods return REDACTED/MASKED data for safety\nconst card = await moon.cards.get(cardId);         // PAN: ****1234\nconst cvv = await moon.cards.getCvv(cardId);       // CVV: ***\nconst pin = await moon.cards.getPin(cardId);       // PIN: [REDACTED]\n```\n\n#### Sensitive Data Access Methods\n```typescript\n// ⚠️ These methods return ACTUAL unredacted data - use with extreme caution!\nconst { pan } = await moon.cards.getUnredactedPAN(cardId);  // Actual PAN\nconst { cvv } = await moon.cards.getUnredactedCVV(cardId);  // Actual CVV  \nconst { pin } = await moon.cards.getUnredactedPIN(cardId);  // Actual PIN\n\n// Maximum risk: Get all sensitive data at once\nconst all = await moon.cards.getAllSensitiveData(cardId);   // All unredacted\n```\n\n#### Security Measures for Sensitive Access\n- **Heavy Audit Logging**: All access logged with `[CRITICAL-AUDIT]` tags\n- **Environment Tracking**: Logs include environment information\n- **Timestamp Recording**: Precise access time tracking\n- **Card ID Masking**: Even audit logs mask card identifiers\n- **Access Warnings**: Clear warnings about data sensitivity\n\n#### Implementation Details\nThe sensitive data access methods use existing Moon API endpoints:\n- **PAN & CVV**: Retrieved from the regular card endpoint (`/v1/api-gateway/card/{id}`)\n- **PIN**: Retrieved from the dedicated PIN endpoint (`/v1/api-gateway/card/{id}/pin`)\n- **All Data**: Combines multiple endpoint calls for comprehensive access\n\nThis approach ensures compatibility with the actual Moon API while maintaining security logging and audit trails.\n\n### ⚠️ CRITICAL SECURITY WARNING\n\nThe sensitive data access methods (`getUnredactedPAN`, `getUnredactedCVV`, `getUnredactedPIN`, `getAllSensitiveData`) return **ACTUAL UNREDACTED** sensitive data. This represents a maximum security risk and should only be used for legitimate business purposes.\n\n**Before using these methods:**\n1. Ensure you have proper authorization/permissions\n2. Implement additional authentication (2FA, biometric, etc.)\n3. Use environment-based access controls\n4. Never log the returned sensitive values\n5. Clear sensitive data from memory after use\n6. Monitor and audit all access attempts\n7. Consider if you truly need unredacted data vs. masked data\n\n### Webhook Security\n- HMAC-SHA256 signature validation\n- Replay attack protection with timestamp validation\n- Automatic idempotency handling\n- Secure error handling\n\n### JIT Authorization\n- Sub-second response time enforcement\n- Rate limiting per card\n- Request validation and sanitization\n- Comprehensive audit logging\n\n### API Key Management\n- Automatic rotation tracking\n- Environment-specific security recommendations\n- Usage monitoring and analytics\n- Secure key masking for logs\n\nSee [SECURITY.md](./SECURITY.md) for complete security documentation.\n\n## Webhook Support\n\nFull webhook security implementation with HMAC validation:\n\n```typescript\nimport { createWebhookMiddleware, createWebhookConfig } from 'moon-card-issuing-sdk';\n\n// CRITICAL: Never use hardcoded secrets or fallbacks\nif (!process.env.MOON_WEBHOOK_SECRET) {\n  throw new Error('MOON_WEBHOOK_SECRET environment variable is required');\n}\n\nconst config = createWebhookConfig(process.env.MOON_WEBHOOK_SECRET);\n\napp.post('/webhooks/moon', \n  createWebhookMiddleware(config, async (payload) => {\n    console.log('Secure webhook received:', payload.type);\n  })\n);\n```\n\n## API Coverage\n\n### Implemented Resources\n- ✅ **Cards** - Full CRUD, balance management, transactions, PIN management\n- ✅ **Webhooks** - Register and delete webhook endpoints with security validation\n- ✅ **Gift Cards** - Purchase, manage, and track branded gift cards\n- ✅ **Cardholders** - Identity management, two-factor authentication, card associations\n- ⏳ **Invoices** - Coming soon  \n- ⏳ **Velocity Controls** - Coming soon\n- ⏳ **Organizations** - Coming soon\n- ⏳ **Accounts** - Coming soon\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and add tests\n4. Run tests: `npm test`\n5. Commit changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- [Documentation](https://docs.paywithmoon.com)\n- [API Reference](https://docs.paywithmoon.com/reference)  \n- [GitHub Issues](https://github.com/paywithmoon/typescript-sdk/issues)\n- Email: support@paywithmoon.com","readmeFilename":"README.md"}