app_store_dev_api 0.3.0 → 0.3.1

data/docs/bundle_ids.md

@@ -0,0 +1,417 @@
+# Bundle IDs - App Store Connect API
+
+> 官方文档: https://developer.apple.com/documentation/appstoreconnectapi/bundle-ids
+
+## 概述
+
+Bundle IDs 是用于标识 iOS、macOS 或通用平台应用的唯一标识符。通过 App Store Connect API，你可以注册、查询、更新和删除 Bundle ID，并管理其关联的 App、Capabilities 和 Profiles。
+
+## 数据模型
+
+### BundleId 对象
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `type` | string | 固定值 `"bundleIds"` |
+| `id` | string | 资源唯一标识 |
+| `attributes.name` | string | Bundle ID 显示名称 |
+| `attributes.platform` | BundleIdPlatform | 平台类型 |
+| `attributes.identifier` | string | Bundle ID 标识符（如 `com.example.app`） |
+| `attributes.seedId` | string | Team Seed ID |
+
+### BundleIdPlatform 枚举
+
+| 值 | 说明 |
+|----|------|
+| `IOS` | iOS 平台 |
+| `MAC_OS` | macOS 平台 |
+| `UNIVERSAL` | 通用平台（iOS + macOS） |
+
+### 关联关系 (Relationships)
+
+| 关系 | 类型 | 说明 |
+|------|------|------|
+| `profiles` | Profiles[] | 关联的配置文件 |
+| `bundleIdCapabilities` | BundleIdCapability[] | 关联的能力配置 |
+| `app` | App | 关联的应用 |
+
+---
+
+## API 端点
+
+### 1. 列出所有 Bundle IDs
+
+```
+GET /v1/bundleIds
+```
+
+获取所有已注册的 Bundle ID 列表。
+
+#### 查询参数
+
+**过滤 (Filter)**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `filter[name]` | string | 按名称过滤 |
+| `filter[platform]` | string | 按平台过滤，可选值: `IOS`, `MAC_OS`, `UNIVERSAL` |
+| `filter[identifier]` | string | 按标识符过滤 |
+| `filter[seedId]` | string | 按 Seed ID 过滤 |
+| `filter[id]` | string | 按资源 ID 过滤 |
+
+**排序 (Sort)**
+
+| 参数 | 说明 |
+|------|------|
+| `sort` | 排序字段，可选: `name`, `-name`, `platform`, `-platform`, `identifier`, `-identifier`, `seedId`, `-seedId`, `id`, `-id` |
+
+**字段选择 (Fields)**
+
+| 参数 | 可选值 |
+|------|--------|
+| `fields[bundleIds]` | `name`, `platform`, `identifier`, `seedId`, `profiles`, `bundleIdCapabilities`, `app` |
+| `fields[profiles]` | `name`, `platform`, `profileType`, `profileState`, `profileContent`, `uuid`, `createdDate`, `expirationDate`, `bundleId`, `devices`, `certificates` |
+| `fields[bundleIdCapabilities]` | `capabilityType`, `settings` |
+| `fields[apps]` | `name`, `bundleId`, `sku`, `primaryLocale` 等 |
+
+**分页与包含**
+
+| 参数 | 说明 |
+|------|------|
+| `limit` | 每页数量限制 |
+| `limit[bundleIdCapabilities]` | Capabilities 关系数量限制 |
+| `limit[profiles]` | Profiles 关系数量限制 |
+| `include` | 包含关联资源，可选: `profiles`, `bundleIdCapabilities`, `app` |
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 200 | 成功 | `BundleIdsResponse` |
+| 400 | 请求参数错误 | `ErrorResponse` |
+| 401 | 未认证 | `ErrorResponse` |
+| 403 | 无权限 | `ErrorResponse` |
+| 429 | 请求过于频繁 | `ErrorResponse` |
+
+---
+
+### 2. 注册新的 Bundle ID
+
+```
+POST /v1/bundleIds
+```
+
+注册一个新的 Bundle ID。
+
+#### 请求体 (BundleIdCreateRequest)
+
+```json
+{
+  "data": {
+    "type": "bundleIds",
+    "attributes": {
+      "name": "My App Bundle ID",
+      "platform": "IOS",
+      "identifier": "com.example.myapp",
+      "seedId": "XXXXXXXXXX"
+    }
+  }
+}
+```
+
+**必填字段:**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `attributes.name` | string | **必填** - Bundle ID 显示名称 |
+| `attributes.platform` | BundleIdPlatform | **必填** - 平台类型 |
+| `attributes.identifier` | string | **必填** - Bundle ID 标识符 |
+
+**可选字段:**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `attributes.seedId` | string | 可选 - Team Seed ID（nullable） |
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 201 | 创建成功 | `BundleIdResponse` |
+| 400 | 请求参数错误 | `ErrorResponse` |
+| 401 | 未认证 | `ErrorResponse` |
+| 403 | 无权限 | `ErrorResponse` |
+| 409 | 资源冲突（已存在） | `ErrorResponse` |
+| 422 | 请求体无法处理 | `ErrorResponse` |
+| 429 | 请求过于频繁 | `ErrorResponse` |
+
+---
+
+### 3. 获取单个 Bundle ID
+
+```
+GET /v1/bundleIds/{id}
+```
+
+根据 ID 获取指定的 Bundle ID 信息。
+
+#### 路径参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | **必填** - Bundle ID 资源的唯一标识 |
+
+#### 查询参数
+
+| 参数 | 说明 |
+|------|------|
+| `fields[bundleIds]` | 选择返回的 Bundle ID 字段 |
+| `fields[profiles]` | 选择返回的 Profile 字段 |
+| `fields[bundleIdCapabilities]` | 选择返回的 Capability 字段 |
+| `fields[apps]` | 选择返回的 App 字段 |
+| `include` | 包含关联资源: `profiles`, `bundleIdCapabilities`, `app` |
+| `limit[bundleIdCapabilities]` | Capabilities 数量限制 |
+| `limit[profiles]` | Profiles 数量限制 |
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 200 | 成功 | `BundleIdResponse` |
+| 400 | 请求参数错误 | `ErrorResponse` |
+| 401 | 未认证 | `ErrorResponse` |
+| 403 | 无权限 | `ErrorResponse` |
+| 404 | 资源不存在 | `ErrorResponse` |
+| 429 | 请求过于频繁 | `ErrorResponse` |
+
+---
+
+### 4. 更新 Bundle ID
+
+```
+PATCH /v1/bundleIds/{id}
+```
+
+更新已有 Bundle ID 的名称。
+
+#### 路径参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | **必填** - Bundle ID 资源的唯一标识 |
+
+#### 请求体 (BundleIdUpdateRequest)
+
+```json
+{
+  "data": {
+    "type": "bundleIds",
+    "id": "BUNDLE_ID_RESOURCE_ID",
+    "attributes": {
+      "name": "Updated App Name"
+    }
+  }
+}
+```
+
+**可更新字段:**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `attributes.name` | string | 可选 - 新的显示名称（nullable） |
+
+> 注意: `platform` 和 `identifier` 字段在创建后不可修改。
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 200 | 更新成功 | `BundleIdResponse` |
+| 400 | 请求参数错误 | `ErrorResponse` |
+| 401 | 未认证 | `ErrorResponse` |
+| 403 | 无权限 | `ErrorResponse` |
+| 404 | 资源不存在 | `ErrorResponse` |
+| 409 | 资源冲突 | `ErrorResponse` |
+| 422 | 请求体无法处理 | `ErrorResponse` |
+| 429 | 请求过于频繁 | `ErrorResponse` |
+
+---
+
+### 5. 删除 Bundle ID
+
+```
+DELETE /v1/bundleIds/{id}
+```
+
+删除指定的 Bundle ID。
+
+#### 路径参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | **必填** - Bundle ID 资源的唯一标识 |
+
+#### 响应
+
+| 状态码 | 说明 |
+|--------|------|
+| 204 | 删除成功（无响应体） |
+| 400 | 请求参数错误 |
+| 401 | 未认证 |
+| 403 | 无权限 |
+| 404 | 资源不存在 |
+| 429 | 请求过于频繁 |
+
+---
+
+## 关联端点
+
+### 6. 获取 Bundle ID 关联的 App（关系）
+
+```
+GET /v1/bundleIds/{id}/relationships/app
+```
+
+获取 Bundle ID 与 App 的关联关系 ID。
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 200 | 成功 | `BundleIdAppLinkageResponse` |
+| 404 | 资源不存在 | `ErrorResponse` |
+
+---
+
+### 7. 获取 Bundle ID 关联的 App（详情）
+
+```
+GET /v1/bundleIds/{id}/app
+```
+
+获取与 Bundle ID 关联的 App 完整信息。
+
+#### 查询参数
+
+| 参数 | 说明 |
+|------|------|
+| `fields[apps]` | 选择返回的 App 字段 |
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 200 | 成功 | `AppWithoutIncludesResponse` |
+| 404 | 资源不存在 | `ErrorResponse` |
+
+---
+
+### 8. 获取 Bundle ID 关联的 Capabilities（关系）
+
+```
+GET /v1/bundleIds/{id}/relationships/bundleIdCapabilities
+```
+
+获取 Bundle ID 与 Capabilities 的关联关系 ID 列表。
+
+#### 查询参数
+
+| 参数 | 说明 |
+|------|------|
+| `limit` | 数量限制 |
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 200 | 成功 | `BundleIdBundleIdCapabilitiesLinkagesResponse` |
+| 404 | 资源不存在 | `ErrorResponse` |
+
+---
+
+### 9. 获取 Bundle ID 关联的 Capabilities（详情）
+
+```
+GET /v1/bundleIds/{id}/bundleIdCapabilities
+```
+
+获取与 Bundle ID 关联的所有 Capability 完整信息。
+
+#### 查询参数
+
+| 参数 | 说明 |
+|------|------|
+| `fields[bundleIdCapabilities]` | 选择返回的字段: `capabilityType`, `settings` |
+| `limit` | 数量限制 |
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 200 | 成功 | `BundleIdCapabilitiesWithoutIncludesResponse` |
+| 404 | 资源不存在 | `ErrorResponse` |
+
+---
+
+### 10. 获取 Bundle ID 关联的 Profiles（关系）
+
+```
+GET /v1/bundleIds/{id}/relationships/profiles
+```
+
+获取 Bundle ID 与 Profiles 的关联关系 ID 列表。
+
+#### 查询参数
+
+| 参数 | 说明 |
+|------|------|
+| `limit` | 数量限制 |
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 200 | 成功 | `BundleIdProfilesLinkagesResponse` |
+| 404 | 资源不存在 | `ErrorResponse` |
+
+---
+
+### 11. 获取 Bundle ID 关联的 Profiles（详情）
+
+```
+GET /v1/bundleIds/{id}/profiles
+```
+
+获取与 Bundle ID 关联的所有 Profile 完整信息。
+
+#### 查询参数
+
+| 参数 | 说明 |
+|------|------|
+| `fields[profiles]` | 选择返回的字段 |
+| `limit` | 数量限制 |
+
+#### 响应
+
+| 状态码 | 说明 | 响应体 |
+|--------|------|--------|
+| 200 | 成功 | `ProfilesWithoutIncludesResponse` |
+| 404 | 资源不存在 | `ErrorResponse` |
+
+---
+
+## 端点汇总
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `GET` | `/v1/bundleIds` | 列出所有 Bundle IDs |
+| `POST` | `/v1/bundleIds` | 注册新 Bundle ID |
+| `GET` | `/v1/bundleIds/{id}` | 获取单个 Bundle ID |
+| `PATCH` | `/v1/bundleIds/{id}` | 更新 Bundle ID |
+| `DELETE` | `/v1/bundleIds/{id}` | 删除 Bundle ID |
+| `GET` | `/v1/bundleIds/{id}/relationships/app` | 获取 App 关系 |
+| `GET` | `/v1/bundleIds/{id}/app` | 获取关联 App 详情 |
+| `GET` | `/v1/bundleIds/{id}/relationships/bundleIdCapabilities` | 获取 Capabilities 关系 |
+| `GET` | `/v1/bundleIds/{id}/bundleIdCapabilities` | 获取关联 Capabilities 详情 |
+| `GET` | `/v1/bundleIds/{id}/relationships/profiles` | 获取 Profiles 关系 |
+| `GET` | `/v1/bundleIds/{id}/profiles` | 获取关联 Profiles 详情 |

data/docs/creating_api_keys.md

@@ -0,0 +1,137 @@
+# 创建 App Store Connect API 密钥
+
+> 官方文档: https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api
+
+## 概述
+
+要使用 App Store Connect API，你需要先创建 API 密钥来进行身份认证。Apple 提供了两种类型的 API 密钥：**团队密钥 (Team Keys)** 和 **个人密钥 (Individual Keys)**。
+
+## 密钥类型
+
+### 团队密钥 (Team Keys)
+
+- 由 **Admin（管理员）** 角色创建和管理
+- 作用于整个开发者团队
+- 可分配不同的角色权限
+- 适用于 CI/CD 自动化、后端服务等场景
+
+### 个人密钥 (Individual Keys)
+
+- 由任何团队成员为自己创建
+- 权限范围与创建者的角色一致
+- 适用于个人开发工具和脚本
+
+## 创建步骤
+
+### 前置条件
+
+- 拥有 Apple Developer Program 会员资格
+- 拥有 App Store Connect 的 Admin 角色（创建团队密钥时需要）
+- 访问 [App Store Connect](https://appstoreconnect.apple.com/)
+
+### 创建团队 API 密钥
+
+1. 登录 [App Store Connect](https://appstoreconnect.apple.com/)
+2. 导航到 **用户和访问 (Users and Access)**
+3. 选择 **集成 (Integrations)** 选项卡
+4. 在左侧导航中选择 **App Store Connect API**
+5. 选择 **团队密钥 (Team Keys)** 标签页
+6. 点击 **生成 API 密钥 (Generate API Key)** 或 **+** 按钮
+7. 输入密钥名称（用于标识用途）
+8. 选择密钥的访问权限（角色）
+9. 点击 **生成 (Generate)**
+
+### 密钥角色权限
+
+创建团队密钥时，可分配以下角色：
+
+| 角色 | 说明 |
+|------|------|
+| Admin | 完全管理权限，可执行所有 API 操作 |
+| Finance | 财务数据访问权限 |
+| App Manager | 应用管理权限 |
+| Developer | 开发相关权限 |
+| Marketing | 营销相关权限 |
+| Sales | 销售数据访问权限 |
+| Customer Support | 客户支持权限 |
+| Read Only | 只读访问权限 |
+
+## 密钥属性
+
+创建 API 密钥后，你将获得以下三个关键信息：
+
+### 1. Issuer ID（发行者 ID）
+
+- 格式：UUID（如 `57246542-96fe-1a63-e053-0824d011072a`）
+- 对整个团队唯一，所有 API 密钥共享同一个 Issuer ID
+- 在 App Store Connect 的 **密钥 (Keys)** 页面顶部可以找到
+- 用于 JWT Token 的 `iss` 声明
+
+### 2. Key ID（密钥 ID）
+
+- 格式：10 位字母数字字符串（如 `2X9R4HXF34`）
+- 每个 API 密钥唯一
+- 在密钥列表中显示
+- 用于 JWT Token Header 的 `kid` 字段
+
+### 3. Private Key（私钥）
+
+- 格式：ECDSA P-256 私钥（`.p8` 文件）
+- 使用 ES256 算法
+- **仅在创建时可下载一次**
+
+## 下载私钥
+
+> ⚠️ **重要提示**: 私钥文件 (.p8) 只能在创建后下载一次。如果丢失，需要撤销当前密钥并创建新的。
+
+1. 创建密钥后，点击 **下载 API 密钥 (Download API Key)**
+2. 保存 `.p8` 文件到安全位置
+3. 文件名格式为 `AuthKey_{Key ID}.p8`（如 `AuthKey_2X9R4HXF34.p8`）
+
+### 私钥文件格式
+
+```
+-----BEGIN PRIVATE KEY-----
+MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQg...
+(Base64 编码的 ECDSA P-256 私钥数据)
+...
+-----END PRIVATE KEY-----
+```
+
+## 安全建议
+
+1. **妥善保管私钥** - 将私钥存储在安全的密钥管理系统中（如 Vault、AWS Secrets Manager）
+2. **不要提交到代码仓库** - 将 `.p8` 文件添加到 `.gitignore`
+3. **使用环境变量** - 通过环境变量传递私钥内容，而非硬编码文件路径
+4. **最小权限原则** - 为 API 密钥分配完成任务所需的最小权限角色
+5. **定期轮换** - 定期撤销旧密钥并创建新密钥
+6. **限制密钥数量** - 每个团队最多可创建的活跃密钥数量有限
+
+## 在本项目中使用
+
+使用 `app_store_dev_api` gem 时，需要提供以上三个凭证信息：
+
+```ruby
+require 'app_store_dev_api'
+
+# 方式一：直接传入私钥内容
+client = AppStoreDevApi::Client.new(
+  issuer_id: '57246542-96fe-1a63-e053-0824d011072a',
+  key_id: '2X9R4HXF34',
+  private_key: File.read('/path/to/AuthKey_2X9R4HXF34.p8')
+)
+
+# 方式二：通过环境变量
+client = AppStoreDevApi::Client.new(
+  issuer_id: ENV['APP_STORE_CONNECT_ISSUER_ID'],
+  key_id: ENV['APP_STORE_CONNECT_KEY_ID'],
+  private_key: ENV['APP_STORE_CONNECT_PRIVATE_KEY']
+)
+```
+
+初始化后，gem 会自动处理 JWT Token 的生成和 API 请求认证。
+
+## 相关文档
+
+- [生成 API 请求 Token](generating_tokens.md)
+- [撤销 API 密钥](revoking_api_keys.md)