creem 0.0.1

data/README.md

@@ -0,0 +1,193 @@
+# Creem Ruby SDK
+
+Ruby SDK for the [Creem](https://creem.io) payment platform API — a Merchant of Record for SaaS and digital businesses.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "creem"
+```
+
+Or install directly:
+
+```bash
+gem install creem
+```
+
+## Quick Start
+
+```ruby
+require "creem"
+
+# Global configuration
+Creem.configure do |config|
+  config.api_key = "creem_YOUR_API_KEY"
+  config.test_mode = true  # Use sandbox environment
+end
+
+client = Creem::Client.new
+
+# Or pass options directly
+client = Creem::Client.new(api_key: "creem_YOUR_API_KEY", test_mode: true)
+```
+
+## Usage
+
+### Products
+
+```ruby
+# List products
+products = client.products.list(page_number: 1, page_size: 10)
+
+# Get a product
+product = client.products.retrieve("prod_123")
+```
+
+### Checkouts
+
+```ruby
+# Create a checkout session
+checkout = client.checkouts.create(
+  product_id: "prod_123",
+  success_url: "https://yoursite.com/success"
+)
+
+puts checkout["checkout_url"]  # Redirect customer here
+```
+
+### Subscriptions
+
+```ruby
+# List subscriptions
+subs = client.subscriptions.list
+
+# Get a subscription
+sub = client.subscriptions.retrieve("sub_123")
+
+# Update a subscription
+client.subscriptions.update("sub_123",
+  items: [{ product_id: "prod_456", units: 3 }],
+  update_behavior: "proration-charge"
+)
+
+# Cancel a subscription
+client.subscriptions.cancel("sub_123", mode: "immediate")
+```
+
+### Customers
+
+```ruby
+# List customers
+customers = client.customers.list
+
+# Get by ID or email
+customer = client.customers.retrieve(customer_id: "cust_123")
+customer = client.customers.retrieve(email: "user@example.com")
+
+# Generate billing portal link
+portal = client.customers.billing_portal("cust_123")
+puts portal["customer_portal_link"]
+```
+
+### Licenses
+
+```ruby
+# Activate a license
+license = client.licenses.activate(key: "ABC-123", instance_name: "My Device")
+
+# Validate a license
+license = client.licenses.validate(key: "ABC-123", instance_id: "inst_456")
+
+# Deactivate a license
+client.licenses.deactivate(key: "ABC-123", instance_id: "inst_456")
+```
+
+### Transactions
+
+```ruby
+transactions = client.transactions.list(page_number: 1, page_size: 10)
+```
+
+### Discounts
+
+```ruby
+discounts = client.discounts.list(page_number: 1, page_size: 10)
+```
+
+## Webhook Verification
+
+```ruby
+# Verify webhook signature
+payload = request.body.read
+signature = request.headers["creem-signature"]
+secret = "whsec_your_webhook_secret"
+
+# Returns parsed event or raises Creem::WebhookSignatureError
+event = Creem::Webhook.construct_event(
+  payload: payload,
+  secret: secret,
+  signature: signature
+)
+
+case event["event"]
+when "checkout.completed"
+  # Handle checkout completion
+when "subscription.active"
+  # Handle new subscription
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.products.retrieve("prod_invalid")
+rescue Creem::AuthenticationError => e
+  puts "Invalid API key: #{e.message}"
+rescue Creem::NotFoundError => e
+  puts "Resource not found: #{e.message}"
+rescue Creem::BadRequestError => e
+  puts "Bad request: #{e.message}"
+rescue Creem::RateLimitError => e
+  puts "Rate limited: #{e.message}"
+rescue Creem::ServerError => e
+  puts "Server error: #{e.message}"
+rescue Creem::ApiError => e
+  puts "API error (#{e.status}): #{e.message}"
+end
+```
+
+## Test Mode
+
+Toggle between production and sandbox environments:
+
+```ruby
+# Via configuration
+Creem.configure do |config|
+  config.test_mode = ENV["RAILS_ENV"] != "production"
+end
+
+# Or per-client
+client = Creem::Client.new(api_key: "key", test_mode: true)
+```
+
+| | Production | Test Mode |
+|---|---|---|
+| Base URL | `https://api.creem.io/v1` | `https://test-api.creem.io/v1` |
+| Payments | Real charges | Simulated |
+
+## Development
+
+```bash
+make install    # Install dependencies
+make test       # Run tests
+make lint       # Run linters
+make format     # Auto-fix formatting
+make console    # Interactive console
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require_relative "lib/creem/version"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/creem.gemspec

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "lib/creem/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "creem"
+  spec.version       = Creem::VERSION
+  spec.authors       = ["Creem Contributors"]
+  spec.email         = ["richard.sun@ai-firstly.com"]
+  spec.summary       = "Ruby SDK for the Creem payment platform API"
+  spec.description   = "Official Ruby SDK for Creem - a Merchant of Record platform for SaaS and digital businesses. " \
+                       "Manage products, checkouts, subscriptions, customers, transactions, licenses, and discounts."
+  spec.homepage      = "https://github.com/ai-firstly/creem-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = [">= 3.3.0", "< 5.0"]
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ai-firstly/creem-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/ai-firstly/creem-ruby/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/creem"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/ai-firstly/creem-ruby/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    if File.exist?(".git")
+      `git ls-files -z`.split("\x0").reject do |f|
+        f.match(%r{\A(?:test|spec|features)/})
+      end
+    else
+      Dir.glob("**/*").reject do |f|
+        File.directory?(f) ||
+          f.match(%r{\A(?:test|spec|features)/}) ||
+          f.match(/\A\./) ||
+          f.match(/\.gem$/)
+      end
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "net-http", ">= 0"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "webmock", "~> 3.18"
+end

data/docs/api_reference.md

@@ -0,0 +1,335 @@
+# API 参考
+
+Creem Ruby SDK 提供以下资源模块，均通过 `Creem::Client` 实例访问。所有方法返回解析后的 `Hash`（JSON 响应体）。
+
+---
+
+## Products（产品）
+
+```ruby
+client.products
+```
+
+### `list(page_number: 1, page_size: 10)`
+
+获取产品列表。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `page_number` | Integer | 1 | 页码 |
+| `page_size` | Integer | 10 | 每页数量 |
+
+```ruby
+products = client.products.list(page_number: 1, page_size: 20)
+```
+
+**API 端点**：`GET /products/search`
+
+### `retrieve(product_id)`
+
+获取单个产品。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `product_id` | String | 产品 ID |
+
+```ruby
+product = client.products.retrieve("prod_123")
+```
+
+**API 端点**：`GET /products?product_id=...`
+
+---
+
+## Checkouts（结账）
+
+```ruby
+client.checkouts
+```
+
+### `create(product_id:, success_url: nil, request_id: nil, units: nil, discount_code: nil, customer: nil, custom_fields: nil, metadata: nil)`
+
+创建结账会话。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `product_id` | String | ✅ | 产品 ID |
+| `success_url` | String | - | 支付成功后的回调 URL |
+| `request_id` | String | - | 幂等请求 ID |
+| `units` | Integer | - | 购买数量 |
+| `discount_code` | String | - | 折扣码 |
+| `customer` | Hash | - | 客户信息 |
+| `custom_fields` | Hash | - | 自定义字段 |
+| `metadata` | Hash | - | 元数据 |
+
+```ruby
+checkout = client.checkouts.create(
+  product_id:  "prod_123",
+  success_url: "https://yoursite.com/success",
+  units:       2,
+  metadata:    { order_ref: "ORD-001" }
+)
+
+puts checkout["checkout_url"]  # 重定向客户到此 URL
+```
+
+**API 端点**：`POST /checkouts`
+
+---
+
+## Subscriptions（订阅）
+
+```ruby
+client.subscriptions
+```
+
+### `list(page_number: 1, page_size: 10)`
+
+获取订阅列表。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `page_number` | Integer | 1 | 页码 |
+| `page_size` | Integer | 10 | 每页数量 |
+
+```ruby
+subs = client.subscriptions.list(page_number: 1, page_size: 20)
+```
+
+**API 端点**：`GET /subscriptions/search`
+
+### `retrieve(subscription_id)`
+
+获取单个订阅。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `subscription_id` | String | 订阅 ID |
+
+```ruby
+sub = client.subscriptions.retrieve("sub_123")
+```
+
+**API 端点**：`GET /subscriptions?subscription_id=...`
+
+### `update(id, items: nil, update_behavior: nil)`
+
+更新订阅。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `id` | String | 订阅 ID（路径参数）|
+| `items` | Array\<Hash\> | 订阅项，如 `[{ product_id: "prod_456", units: 3 }]` |
+| `update_behavior` | String | 更新行为，如 `"proration-charge"` |
+
+```ruby
+client.subscriptions.update("sub_123",
+  items: [{ product_id: "prod_456", units: 3 }],
+  update_behavior: "proration-charge"
+)
+```
+
+**API 端点**：`POST /subscriptions/:id`
+
+### `cancel(id, mode: nil, on_execute: nil)`
+
+取消订阅。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `id` | String | 订阅 ID（路径参数）|
+| `mode` | String | 取消模式，如 `"immediate"`, `"at_period_end"` |
+| `on_execute` | String | 执行时的回调行为 |
+
+> **注意**：`on_execute` 在请求体中以 camelCase（`onExecute`）发送，这是 Creem API 要求的格式。
+
+```ruby
+client.subscriptions.cancel("sub_123", mode: "immediate")
+```
+
+**API 端点**：`POST /subscriptions/:id/cancel`
+
+---
+
+## Customers（客户）
+
+```ruby
+client.customers
+```
+
+### `list(page_number: 1, page_size: 50)`
+
+获取客户列表。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `page_number` | Integer | 1 | 页码 |
+| `page_size` | Integer | 50 | 每页数量 |
+
+```ruby
+customers = client.customers.list(page_number: 1, page_size: 20)
+```
+
+**API 端点**：`GET /customers/list`
+
+### `retrieve(customer_id: nil, email: nil)`
+
+通过 ID 或邮箱获取客户。至少传入一个参数。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `customer_id` | String | 客户 ID |
+| `email` | String | 客户邮箱 |
+
+```ruby
+# 按 ID 查询
+customer = client.customers.retrieve(customer_id: "cust_123")
+
+# 按邮箱查询
+customer = client.customers.retrieve(email: "user@example.com")
+```
+
+**API 端点**：`GET /customers`
+
+### `billing_portal(customer_id)`
+
+生成客户的账单门户链接。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `customer_id` | String | 客户 ID |
+
+```ruby
+portal = client.customers.billing_portal("cust_123")
+puts portal["customer_portal_link"]
+```
+
+**API 端点**：`POST /customers/billing-portal`
+
+---
+
+## Transactions（交易）
+
+```ruby
+client.transactions
+```
+
+### `list(page_number: 1, page_size: 10)`
+
+获取交易列表。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `page_number` | Integer | 1 | 页码 |
+| `page_size` | Integer | 10 | 每页数量 |
+
+```ruby
+transactions = client.transactions.list(page_number: 1, page_size: 20)
+```
+
+**API 端点**：`GET /transactions/search`
+
+---
+
+## Licenses（许可证）
+
+```ruby
+client.licenses
+```
+
+### `list(page_number: 1, page_size: 10)`
+
+获取许可证列表。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `page_number` | Integer | 1 | 页码 |
+| `page_size` | Integer | 10 | 每页数量 |
+
+```ruby
+licenses = client.licenses.list
+```
+
+**API 端点**：`GET /licenses/search`
+
+### `activate(key:, instance_name:)`
+
+激活许可证。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `key` | String | ✅ | 许可证密钥 |
+| `instance_name` | String | ✅ | 实例名称 |
+
+```ruby
+result = client.licenses.activate(key: "ABC-123", instance_name: "My Device")
+puts result["instance_id"]  # 保存此 ID 用于后续验证/停用
+```
+
+**API 端点**：`POST /licenses/activate`
+
+### `validate(key:, instance_id:)`
+
+验证许可证是否有效。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `key` | String | ✅ | 许可证密钥 |
+| `instance_id` | String | ✅ | 实例 ID |
+
+```ruby
+result = client.licenses.validate(key: "ABC-123", instance_id: "inst_456")
+```
+
+**API 端点**：`POST /licenses/validate`
+
+### `deactivate(key:, instance_id:)`
+
+停用许可证。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `key` | String | ✅ | 许可证密钥 |
+| `instance_id` | String | ✅ | 实例 ID |
+
+```ruby
+client.licenses.deactivate(key: "ABC-123", instance_id: "inst_456")
+```
+
+**API 端点**：`POST /licenses/deactivate`
+
+---
+
+## Discounts（折扣）
+
+```ruby
+client.discounts
+```
+
+### `list(page_number: 1, page_size: 10)`
+
+获取折扣列表。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `page_number` | Integer | 1 | 页码 |
+| `page_size` | Integer | 10 | 每页数量 |
+
+```ruby
+discounts = client.discounts.list(page_number: 1, page_size: 20)
+```
+
+**API 端点**：`GET /discounts/search`
+
+---
+
+## 分页
+
+所有 `list` 方法都支持分页，通过 `page_number` 和 `page_size` 参数控制：
+
+```ruby
+# 获取第 2 页，每页 25 条
+products = client.products.list(page_number: 2, page_size: 25)
+```
+
+响应中通常包含分页元数据，可用于构建翻页逻辑。