@exabugs/dynamodb-client 0.5.0 → 0.6.1

package/README.md

@@ -265,6 +265,77 @@ See the [example project's documentation](https://github.com/exabugs/dynamodb-cl
 
 ---
 
+## 🔧 Configuration Management
+
+### Parameter Store Integration
+
+The library supports AWS Parameter Store for flexible configuration management, eliminating the need for Terraform outputs in application code.
+
+#### Parameter Structure
+
+Parameters are organized hierarchically:
+
+```
+/{project_name}/{environment}/
+├── app/
+│   ├── records-api-url          # Lambda Function URL
+│   └── admin-ui/
+│       ├── cognito-user-pool-id
+│       ├── cognito-client-id
+│       └── cognito-domain
+├── infra/
+│   └── dynamodb-table-name
+└── lambda/
+    └── records-function-arn
+```
+
+#### Benefits
+
+- **🔄 Dynamic Configuration**: Update settings without redeployment
+- **🔐 Secure Storage**: All parameters encrypted with AWS managed KMS keys
+- **💰 Cost Effective**: Standard tier is free for typical usage
+- **📊 Audit Trail**: Complete change history via CloudTrail
+- **🎯 Environment Separation**: Clear dev/stg/prd isolation
+
+#### Usage in Applications
+
+**React Admin UI**:
+
+```typescript
+// Read configuration from Parameter Store
+const config = await getParametersByPath(`/${PROJECT_NAME}/${ENV}/app/admin-ui/`);
+
+const cognitoConfig = {
+  userPoolId: config['cognito-user-pool-id'],
+  clientId: config['cognito-client-id'],
+  domain: config['cognito-domain'],
+};
+```
+
+**Lambda Functions**:
+
+```typescript
+// Read specific parameters
+const recordsApiUrl = await getParameter(`/${PROJECT_NAME}/${ENV}/app/records-api-url`);
+```
+
+#### IAM Permissions
+
+The Terraform module automatically creates appropriate IAM policies:
+
+- **Admin UI**: Read access to `/app/admin-ui/*` parameters
+- **Fetch Lambda**: Read access to specific required parameters
+- **Minimal Permissions**: Following least privilege principle
+
+#### Migration from Terraform Outputs
+
+1. **Deploy Parameter Store module** (included in v0.6.0+)
+2. **Update application code** to read from Parameter Store
+3. **Remove Terraform output dependencies**
+4. **Enjoy flexible configuration management**
+
+---
+
 ## 🔧 Shadow Configuration
 
 ### Overview
@@ -273,12 +344,12 @@ The shadow feature automatically makes all fields sortable without requiring JSO
 
 ### Environment Variables
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SHADOW_CREATED_AT_FIELD` | `createdAt` | Field name for creation timestamp |
-| `SHADOW_UPDATED_AT_FIELD` | `updatedAt` | Field name for update timestamp |
-| `SHADOW_STRING_MAX_BYTES` | `100` | Max bytes for primitive types (array/object use 2x) |
-| `SHADOW_NUMBER_PADDING` | `15` | Padding digits for numbers |
+| Variable                  | Default     | Description                                         |
+| ------------------------- | ----------- | --------------------------------------------------- |
+| `SHADOW_CREATED_AT_FIELD` | `createdAt` | Field name for creation timestamp                   |
+| `SHADOW_UPDATED_AT_FIELD` | `updatedAt` | Field name for update timestamp                     |
+| `SHADOW_STRING_MAX_BYTES` | `100`       | Max bytes for primitive types (array/object use 2x) |
+| `SHADOW_NUMBER_PADDING`   | `15`        | Padding digits for numbers                          |
 
 ### Supported Types
 
@@ -300,7 +371,7 @@ const record = {
   viewCount: 123,
   published: true,
   tags: ['tech', 'aws'],
-  metadata: { category: 'tech' }
+  metadata: { category: 'tech' },
 };
 
 // Automatically generates shadow records:

package/dist/server/handler.cjs

@@ -1,5 +1,5 @@
-// @exabugs/dynamodb-client v0.5.0
-// Built: 2025-12-23T05:07:58.552Z
+// @exabugs/dynamodb-client v0.6.1
+// Built: 2025-12-27T04:48:12.419Z
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",

package/terraform/main.tf

@@ -161,3 +161,29 @@ resource "aws_lambda_permission" "function_url" {
   principal              = "*"
   function_url_auth_type = "NONE"
 }
+# Parameter Store モジュール
+module "parameter_store" {
+  source = "./modules/parameter-store"
+
+  # 基本設定
+  project_name = var.project_name
+  environment  = var.environment
+  region       = var.region
+
+  # Records Lambda設定
+  records_function_url = aws_lambda_function_url.records.function_url
+  records_function_arn = aws_lambda_function.records.arn
+
+  # Cognito設定
+  cognito_user_pool_id       = var.cognito_user_pool_id
+  cognito_admin_ui_client_id = var.cognito_admin_ui_client_id
+  cognito_user_pool_domain   = var.cognito_user_pool_domain
+
+  # DynamoDB設定
+  dynamodb_table_name = var.dynamodb_table_name
+
+  depends_on = [
+    aws_lambda_function.records,
+    aws_lambda_function_url.records
+  ]
+}

package/terraform/modules/parameter-store/README.md

@@ -0,0 +1,129 @@
+# Parameter Store Terraform Module
+
+AWS Parameter Storeを使用してアプリケーション設定を管理するTerraformモジュールです。
+
+## 概要
+
+このモジュールは、DynamoDB Clientライブラリを使用するアプリケーションの設定情報をAWS Parameter Storeで管理します。
+
+## 特徴
+
+- **Standard階層**: 標準スループット（1,000 TPS以下）では無料
+- **SecureString**: すべてのパラメータをKMS暗号化で保存
+- **AWS管理キー**: `alias/aws/ssm`を使用（月額料金なし）
+- **階層構造**: `/{project_name}/{environment}/`で環境別に管理
+- **IAMポリシー**: Admin UIとFetch Lambda用のアクセス権限を提供
+
+## 使用方法
+
+```hcl
+module "parameter_store" {
+  source = "./modules/parameter-store"
+
+  # 基本設定
+  project_name = "my-project"
+  environment  = "dev"
+  region       = "us-east-1"
+
+  # Records Lambda設定（必須）
+  records_function_url = aws_lambda_function_url.records.function_url
+  records_function_arn = aws_lambda_function.records.arn
+}
+```
+
+**Note**: このモジュールは外部参照用のプレースホルダーパラメータも作成します。実際の値は他のTerraformモジュール（Cognito、DynamoDB等）から設定してください。
+
+### プレースホルダーパラメータの更新
+
+他のTerraformモジュールから値を設定する例：
+
+```hcl
+# Cognitoモジュールから
+resource "aws_ssm_parameter" "cognito_user_pool_id" {
+  name      = "/${var.project_name}/${var.environment}/app/admin-ui/cognito-user-pool-id"
+  type      = "SecureString"
+  value     = aws_cognito_user_pool.main.id
+  overwrite = true
+}
+
+# DynamoDBモジュールから
+resource "aws_ssm_parameter" "dynamodb_table_name" {
+  name      = "/${var.project_name}/${var.environment}/infra/dynamodb-table-name"
+  type      = "SecureString"
+  value     = aws_dynamodb_table.main.name
+  overwrite = true
+}
+```
+
+## パラメータ構造
+
+### アプリケーション設定 (`/app/`)
+
+- `/{project_name}/{environment}/app/records-api-url`
+- `/{project_name}/{environment}/app/admin-ui/cognito-user-pool-id`
+- `/{project_name}/{environment}/app/admin-ui/cognito-client-id`
+- `/{project_name}/{environment}/app/admin-ui/cognito-domain`
+
+### インフラ情報 (`/infra/`)
+
+- `/{project_name}/{environment}/infra/dynamodb-table-name`
+
+### Lambda情報 (`/lambda/`)
+
+- `/{project_name}/{environment}/lambda/records-function-arn`
+
+## IAMポリシー
+
+### Admin UI用ポリシー
+
+Admin UIが必要とするパラメータへの読み取り権限：
+
+```json
+{
+  "Effect": "Allow",
+  "Action": ["ssm:GetParameter", "ssm:GetParameters", "ssm:GetParametersByPath"],
+  "Resource": ["arn:aws:ssm:region:*:parameter/{project_name}/{environment}/app/*"]
+}
+```
+
+### Fetch Lambda用ポリシー
+
+Fetch Lambdaが必要とする特定パラメータへの読み取り権限：
+
+```json
+{
+  "Effect": "Allow",
+  "Action": ["ssm:GetParameter", "ssm:GetParameters"],
+  "Resource": [
+    "arn:aws:ssm:region:*:parameter/{project_name}/{environment}/app/records-api-url",
+    "arn:aws:ssm:region:*:parameter/{project_name}/{environment}/lambda/records-function-arn"
+  ]
+}
+```
+
+## 出力
+
+- `parameter_arns`: 作成されたパラメータのARN一覧
+- `parameter_names`: 作成されたパラメータの名前一覧
+- `parameter_paths`: 作成されたパラメータのパス一覧
+- `iam_policy_arns`: 作成されたIAMポリシーのARN一覧
+- `iam_policy_names`: 作成されたIAMポリシーの名前一覧
+
+## コスト
+
+- **Parameter Store Standard**: 標準スループット（1,000 TPS以下）では無料
+- **AWS管理キー**: 無料（カスタマー管理キーと異なり月額料金なし）
+- **実質的なコスト**: 通常の使用では完全に無料
+
+## セキュリティ
+
+- すべてのパラメータがKMS暗号化（SecureString）
+- IAMによる細かい権限管理
+- CloudTrailで完全な操作追跡
+- 最小権限の原則に基づくアクセス制御
+
+## 要件
+
+- Terraform >= 1.0
+- AWS Provider >= 4.0
+- 適切なAWS認証情報の設定

package/terraform/modules/parameter-store/iam.tf

@@ -0,0 +1,13 @@
+# Parameter Store アクセス用IAMポリシー
+
+# Note: 実際のプロジェクトでは、以下のようなIAMポリシーを
+# 各リソース（Admin UI、Fetch Lambda等）で個別に定義してください：
+
+# Admin UI用Parameter Store読み取りポリシー例:
+# Resource: "arn:aws:ssm:region:*:parameter/{project_name}/{environment}/app/*"
+
+# Fetch Lambda用Parameter Store読み取りポリシー例:
+# Resource: [
+#   "arn:aws:ssm:region:*:parameter/{project_name}/{environment}/app/records-api-url",
+#   "arn:aws:ssm:region:*:parameter/{project_name}/{environment}/lambda/records-function-arn"
+# ]

package/terraform/modules/parameter-store/main.tf

@@ -0,0 +1,108 @@
+# Parameter Store モジュール
+# AWS Parameter Store を使用してアプリケーション設定を管理
+
+# Parameter Store設定の共通変数
+locals {
+  parameter_tier = "Standard"     # Standard階層を使用（実質無料）
+  parameter_type = "SecureString" # すべてSecureStringで統一
+  # AWS管理キー（alias/aws/ssm）を使用（カスタマー管理キーは禁止）
+}
+
+# Records Lambda Function URL (外部参照用)
+resource "aws_ssm_parameter" "app_records_api_url" {
+  name  = "/${var.project_name}/${var.environment}/app/records-api-url"
+  type  = local.parameter_type
+  tier  = local.parameter_tier
+  value = var.records_function_url
+
+  description = "Records Lambda Function URL"
+
+  tags = {
+    Environment = var.environment
+    ManagedBy   = "terraform"
+    Category    = "app-config"
+  }
+}
+
+# Records Lambda Function ARN (外部参照用)
+resource "aws_ssm_parameter" "lambda_records_function_arn" {
+  name  = "/${var.project_name}/${var.environment}/lambda/records-function-arn"
+  type  = local.parameter_type
+  tier  = local.parameter_tier
+  value = var.records_function_arn
+
+  description = "Records Lambda Function ARN"
+
+  tags = {
+    Environment = var.environment
+    ManagedBy   = "terraform"
+    Category    = "lambda-info"
+  }
+}
+
+# 外部参照用のパラメータ（実際の値を設定）
+# アプリケーション（Admin UI、Fetch Lambda等）がこれらの値を参照する
+
+# Cognito User Pool ID (Admin UI参照用)
+resource "aws_ssm_parameter" "app_admin_ui_cognito_user_pool_id" {
+  name  = "/${var.project_name}/${var.environment}/app/admin-ui/cognito-user-pool-id"
+  type  = local.parameter_type
+  tier  = local.parameter_tier
+  value = var.cognito_user_pool_id
+
+  description = "Cognito User Pool ID for Admin UI"
+
+  tags = {
+    Environment = var.environment
+    ManagedBy   = "terraform"
+    Category    = "app-config"
+  }
+}
+
+# Cognito Client ID (Admin UI参照用)
+resource "aws_ssm_parameter" "app_admin_ui_cognito_client_id" {
+  name  = "/${var.project_name}/${var.environment}/app/admin-ui/cognito-client-id"
+  type  = local.parameter_type
+  tier  = local.parameter_tier
+  value = var.cognito_admin_ui_client_id
+
+  description = "Cognito Client ID for Admin UI"
+
+  tags = {
+    Environment = var.environment
+    ManagedBy   = "terraform"
+    Category    = "app-config"
+  }
+}
+
+# Cognito Domain (Admin UI参照用)
+resource "aws_ssm_parameter" "app_admin_ui_cognito_domain" {
+  name  = "/${var.project_name}/${var.environment}/app/admin-ui/cognito-domain"
+  type  = local.parameter_type
+  tier  = local.parameter_tier
+  value = "${var.cognito_user_pool_domain}.auth.${var.region}.amazoncognito.com"
+
+  description = "Cognito Domain for Admin UI"
+
+  tags = {
+    Environment = var.environment
+    ManagedBy   = "terraform"
+    Category    = "app-config"
+  }
+}
+
+# DynamoDB Table Name (外部参照用)
+resource "aws_ssm_parameter" "infra_dynamodb_table_name" {
+  name  = "/${var.project_name}/${var.environment}/infra/dynamodb-table-name"
+  type  = local.parameter_type
+  tier  = local.parameter_tier
+  value = var.dynamodb_table_name
+
+  description = "DynamoDB Table Name"
+
+  tags = {
+    Environment = var.environment
+    ManagedBy   = "terraform"
+    Category    = "infra-info"
+  }
+}

package/terraform/modules/parameter-store/outputs.tf

@@ -0,0 +1,43 @@
+# Parameter Store モジュール出力
+
+# Parameter Store ARNs
+output "parameter_arns" {
+  description = "作成されたParameter StoreパラメータのARN一覧"
+  value = {
+    records_api_url      = aws_ssm_parameter.app_records_api_url.arn
+    cognito_user_pool_id = aws_ssm_parameter.app_admin_ui_cognito_user_pool_id.arn
+    cognito_client_id    = aws_ssm_parameter.app_admin_ui_cognito_client_id.arn
+    cognito_domain       = aws_ssm_parameter.app_admin_ui_cognito_domain.arn
+    dynamodb_table_name  = aws_ssm_parameter.infra_dynamodb_table_name.arn
+    records_function_arn = aws_ssm_parameter.lambda_records_function_arn.arn
+  }
+}
+
+# Parameter Store Names
+output "parameter_names" {
+  description = "作成されたParameter Storeパラメータの名前一覧"
+  value = {
+    records_api_url      = aws_ssm_parameter.app_records_api_url.name
+    cognito_user_pool_id = aws_ssm_parameter.app_admin_ui_cognito_user_pool_id.name
+    cognito_client_id    = aws_ssm_parameter.app_admin_ui_cognito_client_id.name
+    cognito_domain       = aws_ssm_parameter.app_admin_ui_cognito_domain.name
+    dynamodb_table_name  = aws_ssm_parameter.infra_dynamodb_table_name.name
+    records_function_arn = aws_ssm_parameter.lambda_records_function_arn.name
+  }
+}
+
+# Parameter Store Paths (same as names)
+output "parameter_paths" {
+  description = "作成されたParameter Storeパラメータのパス一覧"
+  value = {
+    records_api_url      = aws_ssm_parameter.app_records_api_url.name
+    cognito_user_pool_id = aws_ssm_parameter.app_admin_ui_cognito_user_pool_id.name
+    cognito_client_id    = aws_ssm_parameter.app_admin_ui_cognito_client_id.name
+    cognito_domain       = aws_ssm_parameter.app_admin_ui_cognito_domain.name
+    dynamodb_table_name  = aws_ssm_parameter.infra_dynamodb_table_name.name
+    records_function_arn = aws_ssm_parameter.lambda_records_function_arn.name
+  }
+}
+
+# Note: IAMポリシーは各プロジェクトで個別に定義してください
+# 詳細は iam.tf のコメントを参照

package/terraform/modules/parameter-store/variables.tf

@@ -0,0 +1,46 @@
+# Parameter Store モジュール変数定義
+
+variable "project_name" {
+  description = "プロジェクト名"
+  type        = string
+}
+
+variable "environment" {
+  description = "環境識別子（dev, stg, prd）"
+  type        = string
+}
+
+variable "region" {
+  description = "AWSリージョン"
+  type        = string
+}
+
+variable "records_function_url" {
+  description = "Records Lambda Function URL"
+  type        = string
+}
+
+variable "records_function_arn" {
+  description = "Records Lambda Function ARN"
+  type        = string
+}
+
+variable "cognito_user_pool_id" {
+  description = "Cognito User Pool ID"
+  type        = string
+}
+
+variable "cognito_admin_ui_client_id" {
+  description = "Admin UI用Cognito User Pool Client ID"
+  type        = string
+}
+
+variable "cognito_user_pool_domain" {
+  description = "Cognito User Pool Domain"
+  type        = string
+}
+
+variable "dynamodb_table_name" {
+  description = "DynamoDB Table Name"
+  type        = string
+}

package/terraform/variables.tf

@@ -36,6 +36,16 @@ variable "cognito_client_id" {
   default     = ""
 }
 
+variable "cognito_user_pool_domain" {
+  description = "Cognito User Pool Domain"
+  type        = string
+}
+
+variable "cognito_admin_ui_client_id" {
+  description = "Admin UI用Cognito User Pool Client ID"
+  type        = string
+}
+
 variable "log_retention_days" {
   description = "CloudWatch Logsの保持期間（日数）"
   type        = number