creem 0.0.1

data/docs/architecture.md

@@ -0,0 +1,145 @@
+# 架构说明
+
+本文档描述 Creem Ruby SDK 的内部架构，适合需要了解源码或贡献代码的开发者。
+
+## 三层架构
+
+```
+┌─────────────────────────────────────────┐
+│  Creem Module + Configuration           │  全局配置层
+│  (lib/creem.rb, configuration.rb)       │
+├─────────────────────────────────────────┤
+│  Creem::Client                          │  HTTP 传输层
+│  (lib/creem/client.rb)                  │
+├─────────────────────────────────────────┤
+│  Creem::Resources::*                    │  资源映射层
+│  (lib/creem/resources/*.rb)             │
+└─────────────────────────────────────────┘
+```
+
+### 1. 全局配置层
+
+`Creem` 模块持有全局 `Configuration` 单例，管理 API Key、超时和环境切换：
+
+- `Creem.configure { |c| ... }` — 设置全局配置
+- `Creem.configuration` — 获取当前配置
+- `Creem.reset_configuration!` — 重置（主要用于测试）
+
+`Configuration` 根据 `test_mode` 自动切换 base URL：
+- 生产：`https://api.creem.io/v1`
+- 沙盒：`https://test-api.creem.io/v1`
+
+### 2. HTTP 传输层（Client）
+
+`Client` 是 SDK 的核心，负责：
+
+1. **配置管理**：初始化时从全局配置拷贝一份，支持参数覆盖
+2. **资源注册**：通过 memoized 方法暴露各资源（`products`, `checkouts` 等）
+3. **HTTP 通信**：使用 `Net::HTTP`，所有请求经过统一管道
+
+请求管道：
+
+```
+request(method, path, params/body)
+  → build_uri(path, params)        # 构建 URL + 查询参数
+  → build_http(uri)                # 配置 Net::HTTP（SSL、超时）
+  → build_request(method, uri, body) # 构建请求对象（Headers、Body）
+  → http.request(req)              # 发送请求
+  → handle_response(response)      # 状态码 → 异常 映射
+```
+
+认证通过 `x-api-key` Header 发送。
+
+### 3. 资源映射层（Resources）
+
+每个资源类继承 `Resources::Base`：
+
+```ruby
+module Creem
+  module Resources
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      def get(path, params = {})
+        client.get(path, params)
+      end
+
+      def post(path, body = {})
+        client.post(path, body)
+      end
+    end
+  end
+end
+```
+
+资源类只负责：
+- 将 Ruby 关键字参数映射为 API 请求参数
+- 不解析响应，直接返回 `JSON.parse` 后的 `Hash`
+
+### API 端点注意事项
+
+不同资源的列表端点路径不统一（反映上游 API 设计）：
+
+| 资源 | 列表端点 |
+|------|----------|
+| Products | `/products/search` |
+| Subscriptions | `/subscriptions/search` |
+| Licenses | `/licenses/search` |
+| Customers | `/customers/list` |
+| Transactions | `/transactions/search` |
+| Discounts | `/discounts/search` |
+
+`retrieve` 通常通过查询参数传递 ID（如 `GET /subscriptions?subscription_id=...`），
+而非路径参数。`Subscriptions#update` 和 `#cancel` 是使用路径参数的例外。
+
+`Subscriptions#cancel` 中 `on_execute` 以 camelCase `onExecute` 发送 — 与 API 保持一致。
+
+## 错误处理架构
+
+见 [错误处理文档](error_handling.md)。
+
+`Client#handle_response` 负责将 HTTP 状态码映射为对应异常类。
+
+## 添加新资源
+
+1. 在 `lib/creem/resources/` 下创建新文件，继承 `Base`
+2. 在 `Client` 中注册 memoized 访问器
+3. 在 `lib/creem.rb` 中 `require_relative` 新文件
+4. 在 `spec/resources/` 下添加对应测试
+
+```ruby
+# lib/creem/resources/invoices.rb
+module Creem
+  module Resources
+    class Invoices < Base
+      def list(page_number: 1, page_size: 10)
+        get("/invoices/search", page_number: page_number, page_size: page_size)
+      end
+    end
+  end
+end
+```
+
+## 文件结构
+
+```
+lib/
+├── creem.rb                  # 入口：require 所有模块，定义常量
+└── creem/
+    ├── version.rb            # 版本号
+    ├── configuration.rb      # 配置类
+    ├── errors.rb             # 异常层级
+    ├── client.rb             # HTTP 客户端
+    ├── webhook.rb            # Webhook 签名验证
+    └── resources/
+        ├── base.rb           # 资源基类
+        ├── products.rb
+        ├── checkouts.rb
+        ├── subscriptions.rb
+        ├── customers.rb
+        ├── transactions.rb
+        ├── licenses.rb
+        └── discounts.rb
+```

data/docs/development.md

@@ -0,0 +1,137 @@
+# 开发指南
+
+本文档面向 Creem Ruby SDK 的贡献者和维护者。
+
+## 环境准备
+
+### 前置要求
+
+- Ruby >= 3.1（项目使用 `.ruby-version` 锁定为 3.3）
+- [mise](https://mise.jdx.dev/) — 运行时版本管理
+- Bundler >= 2.0
+
+### 安装依赖
+
+```bash
+make install
+```
+
+## 常用命令
+
+所有命令通过 `make` 执行，确保使用正确的 Ruby 工具链：
+
+| 命令 | 说明 |
+|------|------|
+| `make install` | 安装依赖 |
+| `make test` | 运行完整测试套件 |
+| `make test TEST=spec/resources/checkouts_spec.rb` | 运行单个测试文件 |
+| `make lint` | 运行 RuboCop 检查 |
+| `make format` | 运行 RuboCop 自动修复 |
+| `make build` | 构建 gem 包 |
+| `make console` | 启动交互式控制台（已加载 creem） |
+| `make clean` | 清理构建产物 |
+| `make tag` | 自动递增 patch 版本并推送 tag |
+| `make tag VERSION=1.0.0` | 指定版本号并推送 tag |
+
+精确到行的测试：
+
+```bash
+mise exec -- bundle exec rspec spec/resources/checkouts_spec.rb:15
+```
+
+## 测试规范
+
+### 约定
+
+- 使用 WebMock 禁止真实网络请求
+- 每个测试前自动重置 `Creem.configuration`
+- 使用 `stub_creem_get` / `stub_creem_post` 辅助方法创建 HTTP 桩
+- 使用 `build_client` 创建测试用客户端
+
+### 示例
+
+```ruby
+RSpec.describe Creem::Resources::Products do
+  let(:client) { build_client }
+
+  describe "#list" do
+    it "returns products" do
+      stub_creem_get("/products/search", { items: [] })
+      result = client.products.list
+      expect(result).to eq({ "items" => [] })
+    end
+  end
+end
+```
+
+### 添加新资源测试
+
+在 `spec/resources/` 下创建 `<resource>_spec.rb`，遵循现有模式：
+
+1. 使用 `build_client` 创建客户端
+2. 使用 `stub_creem_get` / `stub_creem_post` 模拟 HTTP
+3. 验证返回值结构
+4. 验证请求参数正确传递
+
+## 代码风格
+
+项目使用 RuboCop 进行代码风格检查，配置文件为 `.rubocop.yml`。
+
+```bash
+make lint    # 检查
+make format  # 自动修复
+```
+
+## 发布流程
+
+### 自动版本管理
+
+`make tag` 会自动：
+
+1. 获取最新的 git tag
+2. 递增 patch 版本号（或使用指定版本）
+3. 更新 `lib/creem/version.rb`
+4. 提交 "Release vX.Y.Z"
+5. 创建 git tag
+6. 推送 commit 和 tag
+
+### CI/CD
+
+- **CI**（`.github/workflows/ci.yml`）：在 Ruby 3.1 ~ 4.0 上运行测试和 lint
+- **Release**（`.github/workflows/release.yml`）：推送 `v*` tag 时自动发布到 RubyGems 并创建 GitHub Release
+
+### 发布步骤
+
+```bash
+# 1. 确保测试通过
+make test
+
+# 2. 更新 CHANGELOG.md
+
+# 3. 打 tag 并推送（自动触发发布）
+make tag                  # 自动递增 patch
+# 或
+make tag VERSION=1.0.0    # 指定版本
+```
+
+## 项目结构
+
+```
+creem/
+├── .github/workflows/    # CI/CD 配置
+│   ├── ci.yml            # 测试 + lint
+│   └── release.yml       # 发布到 RubyGems
+├── docs/                 # 文档
+├── lib/
+│   ├── creem.rb          # 入口文件
+│   └── creem/            # 核心代码
+├── spec/                 # 测试
+│   ├── spec_helper.rb    # 测试辅助
+│   ├── resources/        # 资源测试
+│   └── ...
+├── Gemfile               # 依赖声明
+├── creem.gemspec         # Gem 规格
+├── Makefile              # 开发命令
+├── CHANGELOG.md          # 变更日志
+└── README.md             # 项目说明
+```

data/docs/error_handling.md

@@ -0,0 +1,85 @@
+# 错误处理
+
+Creem Ruby SDK 使用结构化的异常层级来表示不同类型的错误。
+
+## 异常层级
+
+```
+StandardError
+└── Creem::Error
+    ├── Creem::ConfigurationError
+    ├── Creem::WebhookSignatureError
+    └── Creem::ApiError
+        ├── Creem::BadRequestError       # 400
+        ├── Creem::AuthenticationError   # 401
+        ├── Creem::NotFoundError         # 404
+        ├── Creem::RateLimitError        # 429
+        └── Creem::ServerError           # 5xx
+```
+
+## ApiError 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `message` | String | 错误描述 |
+| `status` | Integer | HTTP 状态码 |
+| `body` | Hash/nil | 响应体 |
+
+## 使用示例
+
+```ruby
+begin
+  client.products.retrieve("prod_invalid")
+rescue Creem::AuthenticationError => e
+  puts "认证失败: #{e.message}"
+rescue Creem::NotFoundError => e
+  puts "未找到: #{e.message}"
+rescue Creem::RateLimitError => e
+  sleep(5)
+  retry
+rescue Creem::BadRequestError => e
+  puts "参数错误: #{e.body}"
+rescue Creem::ServerError => e
+  puts "服务器错误: #{e.message}"
+rescue Creem::ApiError => e
+  puts "API 错误 (#{e.status}): #{e.message}"
+end
+```
+
+## 配置错误
+
+```ruby
+begin
+  client = Creem::Client.new  # 缺少 api_key
+rescue Creem::ConfigurationError => e
+  puts e.message  # => "API key is required"
+end
+```
+
+## 重试策略
+
+| 错误类型 | 可重试 | 建议 |
+|----------|--------|------|
+| `AuthenticationError` | ❌ | 检查 API Key |
+| `BadRequestError` | ❌ | 检查请求参数 |
+| `NotFoundError` | ❌ | 确认资源 ID |
+| `RateLimitError` | ✅ | 指数退避重试 |
+| `ServerError` | ✅ | 等待后重试（最多 3 次）|
+
+### 指数退避示例
+
+```ruby
+def with_retry(max_retries: 3, base_delay: 1)
+  retries = 0
+  begin
+    yield
+  rescue Creem::RateLimitError, Creem::ServerError
+    retries += 1
+    raise if retries > max_retries
+    sleep(base_delay * (2**(retries - 1)))
+    retry
+  end
+end
+
+with_retry { client.products.list }
+```

data/docs/getting_started.md

@@ -0,0 +1,116 @@
+# Getting Started
+
+本指南帮助你快速集成 Creem Ruby SDK，完成从安装到第一次 API 调用的全部流程。
+
+## 系统要求
+
+- **Ruby** >= 3.1.0, < 5.0
+- **Bundler** >= 2.0
+
+## 安装
+
+### 通过 Gemfile（推荐）
+
+```ruby
+# Gemfile
+gem "creem"
+```
+
+然后执行：
+
+```bash
+bundle install
+```
+
+### 直接安装
+
+```bash
+gem install creem
+```
+
+## 配置
+
+### 全局配置
+
+适用于整个应用共享同一组凭据的场景（如 Rails 应用）：
+
+```ruby
+require "creem"
+
+Creem.configure do |config|
+  config.api_key      = "creem_YOUR_API_KEY"   # 必填
+  config.test_mode    = true                    # 使用沙盒环境（默认 false）
+  config.timeout      = 30                      # 读超时，秒（默认 30）
+  config.open_timeout = 10                      # 连接超时，秒（默认 10）
+end
+
+client = Creem::Client.new
+```
+
+> **Rails 项目建议**：将配置放在 `config/initializers/creem.rb` 中。
+
+### 单独配置
+
+也可以在创建 Client 时直接传入配置，覆盖全局设置：
+
+```ruby
+client = Creem::Client.new(
+  api_key:      "creem_YOUR_API_KEY",
+  test_mode:    true,
+  timeout:      60,
+  open_timeout: 15
+)
+```
+
+### 环境变量方式
+
+推荐在生产环境中通过环境变量管理密钥：
+
+```ruby
+Creem.configure do |config|
+  config.api_key   = ENV.fetch("CREEM_API_KEY")
+  config.test_mode = ENV["RAILS_ENV"] != "production"
+end
+```
+
+## 测试模式 vs 生产模式
+
+| 对比项 | 生产模式 | 测试模式 |
+|--------|----------|----------|
+| Base URL | `https://api.creem.io/v1` | `https://test-api.creem.io/v1` |
+| 支付 | 真实扣款 | 模拟支付 |
+| 用途 | 正式环境 | 开发调试 |
+
+**切换方式**：设置 `config.test_mode = true` 即可启用沙盒环境。
+
+## 第一次 API 调用
+
+```ruby
+require "creem"
+
+Creem.configure do |config|
+  config.api_key   = ENV.fetch("CREEM_API_KEY")
+  config.test_mode = true
+end
+
+client = Creem::Client.new
+
+# 获取产品列表
+products = client.products.list
+puts products
+
+# 创建一个结账会话
+checkout = client.checkouts.create(
+  product_id:  "prod_123",
+  success_url: "https://yoursite.com/success"
+)
+
+puts checkout["checkout_url"]  # 将客户重定向到此 URL
+```
+
+## 下一步
+
+- [API 参考](api_reference.md) — 所有资源的详细用法
+- [Webhook 集成](webhooks.md) — 接收和验证 Webhook 事件
+- [错误处理](error_handling.md) — 异常类型和最佳实践
+- [架构说明](architecture.md) — SDK 内部架构和扩展方式

data/docs/webhooks.md

@@ -0,0 +1,179 @@
+# Webhook 集成
+
+Creem 通过 Webhook 推送异步事件通知（如支付完成、订阅变更等）。本文档介绍如何安全接收和处理这些事件。
+
+## 签名验证原理
+
+Creem 使用 **HMAC-SHA256** 算法对 Webhook 请求体进行签名：
+
+1. Creem 使用你的 Webhook Secret 对原始请求体计算 HMAC-SHA256
+2. 签名通过 `creem-signature` HTTP Header 发送
+3. SDK 使用 `OpenSSL.fixed_length_secure_compare` 进行恒时比较，防止时序攻击
+
+## 基本用法
+
+```ruby
+# 验证签名并解析事件（推荐）
+event = Creem::Webhook.construct_event(
+  payload:   raw_body,      # 原始请求体（String）
+  secret:    webhook_secret, # Webhook Secret
+  signature: signature       # creem-signature Header
+)
+# event 是解析后的 Hash
+
+# 仅验证签名（不解析）
+valid = Creem::Webhook.verify_signature(
+  payload:   raw_body,
+  secret:    webhook_secret,
+  signature: signature
+)
+# 返回 true / false
+
+# 验证签名，失败时抛异常
+Creem::Webhook.verify_signature!(
+  payload:   raw_body,
+  secret:    webhook_secret,
+  signature: signature
+)
+# 签名无效时抛出 Creem::WebhookSignatureError
+```
+
+## Rails 集成
+
+```ruby
+# app/controllers/webhooks_controller.rb
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token, only: :creem
+
+  WEBHOOK_SECRET = ENV.fetch("CREEM_WEBHOOK_SECRET")
+
+  def creem
+    payload   = request.body.read
+    signature = request.headers["creem-signature"]
+
+    event = Creem::Webhook.construct_event(
+      payload:   payload,
+      secret:    WEBHOOK_SECRET,
+      signature: signature
+    )
+
+    handle_event(event)
+    head :ok
+  rescue Creem::WebhookSignatureError => e
+    Rails.logger.warn("Webhook signature verification failed: #{e.message}")
+    head :bad_request
+  rescue JSON::ParserError => e
+    Rails.logger.error("Webhook payload parse error: #{e.message}")
+    head :bad_request
+  end
+
+  private
+
+  def handle_event(event)
+    case event["event"]
+    when "checkout.completed"
+      handle_checkout_completed(event)
+    when "subscription.active"
+      handle_subscription_active(event)
+    when "subscription.canceled"
+      handle_subscription_canceled(event)
+    when "subscription.renewed"
+      handle_subscription_renewed(event)
+    else
+      Rails.logger.info("Unhandled webhook event: #{event['event']}")
+    end
+  end
+
+  def handle_checkout_completed(event)
+    # 处理结账完成事件
+    # event["object"] 包含结账详情
+  end
+
+  def handle_subscription_active(event)
+    # 处理订阅激活事件
+  end
+
+  def handle_subscription_canceled(event)
+    # 处理订阅取消事件
+  end
+
+  def handle_subscription_renewed(event)
+    # 处理订阅续费事件
+  end
+end
+```
+
+路由配置：
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  post "/webhooks/creem", to: "webhooks#creem"
+end
+```
+
+## Sinatra 集成
+
+```ruby
+require "sinatra"
+require "creem"
+
+WEBHOOK_SECRET = ENV.fetch("CREEM_WEBHOOK_SECRET")
+
+post "/webhooks/creem" do
+  payload   = request.body.read
+  signature = request.env["HTTP_CREEM_SIGNATURE"]
+
+  begin
+    event = Creem::Webhook.construct_event(
+      payload:   payload,
+      secret:    WEBHOOK_SECRET,
+      signature: signature
+    )
+
+    case event["event"]
+    when "checkout.completed"
+      # 处理结账完成
+    when "subscription.active"
+      # 处理订阅激活
+    end
+
+    status 200
+    body "OK"
+  rescue Creem::WebhookSignatureError
+    status 400
+    body "Invalid signature"
+  end
+end
+```
+
+## 常见事件类型
+
+| 事件名 | 说明 |
+|--------|------|
+| `checkout.completed` | 结账完成，客户已支付 |
+| `subscription.active` | 订阅已激活 |
+| `subscription.canceled` | 订阅已取消 |
+| `subscription.renewed` | 订阅已续费 |
+| `subscription.paused` | 订阅已暂停 |
+
+> 完整的事件列表请参考 [Creem 官方文档](https://docs.creem.io)。
+
+## 最佳实践
+
+1. **始终验证签名**：不要跳过签名验证，防止伪造请求。
+2. **使用原始请求体**：签名基于原始字节流计算，不要对请求体做任何预处理。
+3. **幂等处理**：Webhook 可能重复投递，确保处理逻辑幂等。
+4. **快速响应**：尽快返回 `200` 状态码，将耗时操作放入后台队列。
+5. **记录日志**：记录接收到的事件，便于排查问题。
+6. **处理未知事件**：对不认识的事件类型做优雅降级，不要返回错误。
+
+## 本地测试
+
+开发时可使用 [ngrok](https://ngrok.com) 等工具将本地服务暴露到公网：
+
+```bash
+ngrok http 3000
+```
+
+然后在 Creem 控制台中将 Webhook URL 设置为 ngrok 提供的 HTTPS 地址。