{"_id":"@croco/billing-polar","_rev":"2-9dda884809235e238e2447eb7af7ab82","name":"@croco/billing-polar","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@croco/billing-polar","version":"0.0.1","_id":"@croco/billing-polar@0.0.1","maintainers":[{"name":"kang-heewon","email":"heewon.dev@gmail.com"},{"name":"ddark","email":"ddark.kr@gmail.com"}],"dist":{"shasum":"b60259391af4127ce3ff3a950aa70b9160b07026","tarball":"https://registry.npmjs.org/@croco/billing-polar/-/billing-polar-0.0.1.tgz","fileCount":6,"integrity":"sha512-UbWpqOGgBewl9z37hRCxMH9ZiH6T8joQftliJ2KiJQGEdaSefslTCvXoNVMPBYIIbCEmgY8bav/2CLdE2H8sZA==","signatures":[{"sig":"MEUCIE08drXF98oE8/s3gZPlCF3GJNLLKAMTmN09WzPzBJ6rAiEAiUpKeeWRFOmBPvTKRZ1LuiOhIt3VAGqTFr7AfeBQtJ8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32727},"main":"./dist/index.js","type":"commonjs","_from":"file:croco-billing-polar-0.0.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"lint":"oxlint .","test":"vitest run","build":"tsup src/index.ts --format esm,cjs --minify --clean --dts","typecheck":"tsc --noEmit"},"_npmUser":{"name":"kang-heewon","email":"heewon.dev@gmail.com"},"_resolved":"/tmp/5182186758114ad6c83dea711454934f/croco-billing-polar-0.0.1.tgz","_integrity":"sha512-UbWpqOGgBewl9z37hRCxMH9ZiH6T8joQftliJ2KiJQGEdaSefslTCvXoNVMPBYIIbCEmgY8bav/2CLdE2H8sZA==","_npmVersion":"10.9.7","description":"Polar 결제 플랫폼 연동 — checkout, webhook, 구독 관리","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^4.0.0","@polar-sh/sdk":"^0.32.2","@croco/events-core":"0.0.1","@croco/billing-core":"0.0.1","@croco/problems-core":"0.0.1","@croco/telemetry-api":"0.0.1","@croco/framework-context":"0.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"4.0.16","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/billing-polar_0.0.1_1778834238936_0.7667247624908475","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@croco/billing-polar","version":"0.0.2","type":"commonjs","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js","types":"./dist/index.d.ts"}},"publishConfig":{"access":"public"},"dependencies":{"@polar-sh/sdk":"^0.32.2","zod":"^4.0.0","@croco/billing-core":"0.0.2","@croco/events-core":"0.0.2","@croco/framework-context":"0.0.2","@croco/telemetry-api":"0.0.2","@croco/problems-core":"0.0.2"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.7.0","vitest":"4.0.16"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --minify --clean --dts","lint":"oxlint .","test":"vitest run","typecheck":"tsc --noEmit"},"_id":"@croco/billing-polar@0.0.2","description":"Polar 결제 플랫폼 연동 — checkout, webhook, 구독 관리","_integrity":"sha512-UkqqyIe3rKYfHQOwwK0+AkO8+Wr6VDVvSr/0lDAKqh2yPzygp5qaUqMz6Y3VI/FzJf+ZGCMZ/JVJCNP/ysevRA==","_resolved":"/private/var/folders/zp/px4pj6gs20q8c38hgmbym1080000gn/T/66c205538b2d661298cbcce77760456d/croco-billing-polar-0.0.2.tgz","_from":"file:croco-billing-polar-0.0.2.tgz","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-UkqqyIe3rKYfHQOwwK0+AkO8+Wr6VDVvSr/0lDAKqh2yPzygp5qaUqMz6Y3VI/FzJf+ZGCMZ/JVJCNP/ysevRA==","shasum":"253bedef74b6065d301e0f9b98a62c7c5e5d05f5","tarball":"https://registry.npmjs.org/@croco/billing-polar/-/billing-polar-0.0.2.tgz","fileCount":6,"unpackedSize":32727,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBI4+kO6+gigy4dkIWlL8AkqRwFFW8dan/crtP+faGKkAiAy3yK+tn8rKFYx83G0Bc2vsfuwOp9M24O3TMyqcn85pw=="}]},"_npmUser":{"name":"kang-heewon","email":"heewon.dev@gmail.com"},"directories":{},"maintainers":[{"name":"kang-heewon","email":"heewon.dev@gmail.com"},{"name":"ddark","email":"ddark.kr@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/billing-polar_0.0.2_1780294742196_0.6017407347416055"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-15T08:37:18.861Z","modified":"2026-06-01T06:19:02.486Z","0.0.1":"2026-05-15T08:37:19.121Z","0.0.2":"2026-06-01T06:19:02.357Z"},"description":"Polar 결제 플랫폼 연동 — checkout, webhook, 구독 관리","maintainers":[{"name":"kang-heewon","email":"heewon.dev@gmail.com"},{"name":"ddark","email":"ddark.kr@gmail.com"}],"readme":"# @croco/billing-polar\n\nPolar 결제 플랫폼 연동 — checkout, webhook, 구독 관리\n\n## 설치\n\n```bash\npnpm add @croco/billing-polar\n```\n\n## 개요\n\nPolar 결제 플랫폼을 `@croco/billing-core`와 통합하여 SaaS 구독 비즈니스를 구축합니다.\n\n- **Checkout**: Polar checkout 세션 생성\n- **Webhook**: 서명 검증, 멱등성, 이벤트 매핑\n- **구독 관리**: 활성화/취소/재개, 고객 포털 URL\n\n## 구성\n\n```typescript\nimport { PolarConfig } from \"@croco/billing-polar\";\n\nconst config: PolarConfig = {\n  accessToken: \"polar-access-token\",\n  environment: \"sandbox\",\n  webhookSecret: \"polar-webhook-secret\",\n  organizationId: \"org-123\",\n};\n```\n\n### PolarConfig\n\n| 필드             | 타입                        | 필수 | 설명                  |\n| ---------------- | --------------------------- | ---- | --------------------- |\n| `accessToken`    | `string`                    | ✅   | Polar API 액세스 토큰 |\n| `environment`    | `'sandbox' \\| 'production'` | ✅   | Polar 환경            |\n| `webhookSecret`  | `string`                    | ✅   | 웹훅 서명 검증 시크릿 |\n| `organizationId` | `string`                    | ❌   | Polar 조직 ID         |\n\n## 사용법\n\n### Checkout 생성\n\n```typescript\nimport { Container } from \"@croco/framework-context\";\nimport { PolarBillingGateway } from \"@croco/billing-polar\";\n\nconst gateway = Container.get(PolarBillingGateway);\n\nconst checkout = await gateway.createCheckout({\n  billingAccountId: \"tenant-123\",\n  email: \"user@example.com\",\n  productId: \"prod-456\",\n  successUrl: \"https://example.com/success\",\n  cancelUrl: \"https://example.com/cancel\",\n});\n```\n\n### 구독 관리\n\n```typescript\nawait gateway.cancelSubscription(\"sub-789\", false);\nawait gateway.resumeSubscription(\"sub-789\");\nconst portalUrl = await gateway.getCustomerPortalUrl(\"cust-101\");\n```\n\n### 웹훅 처리\n\n```typescript\nimport { PolarWebhookHandler } from \"@croco/billing-polar\";\n\nconst handler = new PolarWebhookHandler(config, {\n  store: billingStore,\n  eventPublisher: eventPublisher,\n});\n\nconst result = await handler.handle(requestBody, requestHeaders);\n```\n\n## 웹훅 이벤트 타입\n\n### 구독 이벤트\n\n| 이벤트 타입             | 설명          |\n| ----------------------- | ------------- |\n| `subscription.created`  | 구독 생성     |\n| `subscription.active`   | 구독 활성화   |\n| `subscription.updated`  | 구독 업데이트 |\n| `subscription.canceled` | 구독 취소     |\n| `subscription.revoked`  | 구독 해지     |\n| `subscription.past_due` | 결제 지연     |\n\n### 주문 이벤트\n\n| 이벤트 타입     | 설명           |\n| --------------- | -------------- |\n| `order.paid`    | 주문 결제 완료 |\n| `order.created` | 주문 생성      |\n| `order.updated` | 주문 업데이트  |\n\n## 멱등성\n\nPolar 웹훅은 `eventId`를 멱등성 키로 사용합니다:\n\n- 같은 `eventId`는 한 번만 처리됩니다\n- 진행 중인 이벤트는 메모리에서 추적하여 중복 실행 방지\n- 처리 실패 시 `unmarkWebhookProcessed`로 롤백 지원\n\n## 스키마\n\n### PolarSubscriptionData\n\n```typescript\ntype PolarSubscriptionData = {\n  id: string;\n  status: \"active\" | \"past_due\" | \"canceled\" | \"revoked\" | \"trialing\";\n  customer?: {\n    externalId?: string | null;\n    metadata?: Record<string, unknown> | null;\n  };\n  product?: {\n    id?: string;\n  };\n  currentPeriodEnd?: Date | string | null;\n  cancelAtPeriodEnd?: boolean | null;\n};\n```\n\n### PolarOrderData\n\n```typescript\ntype PolarOrderData = {\n  id: string;\n  amount?: number;\n  currency?: string;\n  createdAt?: Date | string | null;\n  customer?: {\n    externalId?: string | null;\n    metadata?: Record<string, unknown> | null;\n  };\n};\n```\n\n## 재시도 정책\n\nPolar API 호출에 자동 재시도 적용:\n\n- **전략**: 지수 백오프\n- **초기 간격**: 500ms\n- **최대 간격**: 5초\n- **최대 경과 시간**: 15초\n- **재시도 코드**: 429, 500, 502, 503, 504\n\n## 에러 처리\n\n```typescript\nimport {\n  WebhookValidationProblem,\n  WebhookProcessingProblem,\n  BillingStatusMappingProblem,\n} from \"@croco/billing-polar\";\n```\n\n| 에러                          | 코드                            | 카테고리            | 설명                 |\n| ----------------------------- | ------------------------------- | ------------------- | -------------------- |\n| `WebhookValidationProblem`    | `WEBHOOK_VALIDATION_FAILED`     | BadRequest          | 웹훅 서명 검증 실패  |\n| `WebhookProcessingProblem`    | `WEBHOOK_PROCESSING_FAILED`     | InternalServerError | 웹훅 처리 실패       |\n| `BillingStatusMappingProblem` | `BILLING_STATUS_MAPPING_FAILED` | InternalServerError | 알 수 없는 결제 상태 |\n\n## 의존성\n\n| 패키지                     | 버전 | 설명             |\n| -------------------------- | ---- | ---------------- |\n| `@croco/billing-core`      | -    | 빌링 도메인 모델 |\n| `@croco/events-core`       | -    | 이벤트 발행/구독 |\n| `@croco/telemetry-api`     | -    | 분산 추적        |\n| `@croco/framework-context` | -    | DI 컨테이너      |\n| `@polar-sh/sdk`            | -    | Polar SDK        |\n| `zod`                      | -    | 스키마 검증      |\n\n## 라이선스\n\nMIT\n\n---\n\n## 성숙도 안내\n\n| 항목                 | 상태                                                                     | 설명                                                                                                           |\n| -------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |\n| **현재 상태**        | 🟡 beta                                                                  | 기능 완성, 실사용 검증 중                                                                                      |\n| **주요 기능**        | Checkout 생성, Webhook 처리, 구독 관리 (활성화/취소/재개), 고객 포털 URL | Polar 플랫폼 핵심 연동 기능                                                                                    |\n| **테스트 존재 여부** | ✅                                                                       | 단위테스트 3개 파일 (`PolarWebhookHandler.spec.ts`, `PolarBillingGateway.spec.ts`, `PolarEventMapper.spec.ts`) |\n| **운영 증거 수준**   | L1                                                                       | 단위테스트 있음 / 통합테스트 미존재 / 샌드박스 미실행 / 프로덕션 미사용                                        |\n\n### 참고\n\n- 이 패키지는 `@croco/billing-core` 인터페이스를 구현합니다.\n- 웹훅 서명 검증과 멱등성 처리가 구현되어 있습니다.\n- 재시도 정책(지수 백오프)이 적용되어 있습니다.\n","readmeFilename":"README.md"}