{"_id":"@daniadelapuenteveliz/sam-smith","_rev":"2-8824df8b727d85a30b48babc6ac8eacb","name":"@daniadelapuenteveliz/sam-smith","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@daniadelapuenteveliz/sam-smith","version":"1.0.0","keywords":["sam","lambda","serverless","aws","api-gateway","typescript","cognito"],"author":{"name":"Dania Ignacia de la Puente Véliz"},"license":"MIT","_id":"@daniadelapuenteveliz/sam-smith@1.0.0","maintainers":[{"name":"daniadelapuenteveliz","email":"daniaignaciadelapuenteveliz@gmail.com"}],"homepage":"https://github.com/daniadelapuenteveliz/sam-smith-typescript#readme","bugs":{"url":"https://github.com/daniadelapuenteveliz/sam-smith-typescript/issues"},"bin":{"sam-smith":"bin/index.js"},"dist":{"shasum":"d256833591546dbcc3655b96f091cdc3e8a269dc","tarball":"https://registry.npmjs.org/@daniadelapuenteveliz/sam-smith/-/sam-smith-1.0.0.tgz","fileCount":23,"integrity":"sha512-kgvXZzZ/bRU8clvDn1XB+/0Vh97J7s0tTUELyyvL3EQRQiWK1i5b+GSXNy7gh9fHTScf3IlIh7rQTzeZLVD1LA==","signatures":[{"sig":"MEUCICww0a9KcydoX7aIWJeTplfROv5sWkHzC4TLtrQOC+kzAiEAmTLw49g5NudBZTf1+9BVv3j5WqTROLrJWSKrDbgGSyI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":336372},"main":"index.js","type":"module","gitHead":"6d50557282ca90482b9cab9017e2f692b14ff36f","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"daniadelapuenteveliz","email":"daniaignaciadelapuenteveliz@gmail.com"},"repository":{"url":"git+https://github.com/daniadelapuenteveliz/sam-smith-typescript.git","type":"git"},"workspaces":["templates"],"_npmVersion":"10.9.2","description":"Helper to build serverless backends in AWS (SAM + Lambda + API Gateway)","directories":{},"_nodeVersion":"22.15.0","dependencies":{"chalk":"^5.6.2","dotenv":"^17.2.3","fs-extra":"^11.3.2","inquirer":"^13.0.2","typescript":"^5.9.3","dynamo-query-builder":"^1.0.1"},"publishConfig":{"access":"restricted"},"_hasShrinkwrap":false,"devDependencies":{"swagger-jsdoc":"^6.2.8"},"_npmOperationalInternal":{"tmp":"tmp/sam-smith_1.0.0_1775947543304_0.448213069687978","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@daniadelapuenteveliz/sam-smith","version":"1.0.1","description":"Helper to build serverless backends in AWS (SAM + Lambda + API Gateway)","main":"index.js","type":"module","bin":{"sam-smith":"bin/index.js"},"workspaces":["templates"],"scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"keywords":["sam","lambda","serverless","aws","api-gateway","typescript","cognito"],"author":{"name":"Dania Ignacia de la Puente Véliz"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/daniadelapuenteveliz/sam-smith-typescript.git"},"bugs":{"url":"https://github.com/daniadelapuenteveliz/sam-smith-typescript/issues"},"homepage":"https://github.com/daniadelapuenteveliz/sam-smith-typescript#readme","dependencies":{"chalk":"^5.6.2","dotenv":"^17.2.3","@daniadelapuenteveliz/dynamo-query-builder":"^1.0.0","fs-extra":"^11.3.2","inquirer":"^13.0.2","typescript":"^5.9.3"},"devDependencies":{"swagger-jsdoc":"^6.2.8"},"publishConfig":{"access":"restricted"},"_id":"@daniadelapuenteveliz/sam-smith@1.0.1","gitHead":"c9c9cb85485ec04fd01e93944665b0507a2c8829","_nodeVersion":"22.15.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-QPpucy8O3j9SJt8cdWSTnXBUO+lNrYzPqjpxxJ0qUnYzl5uJKQoKez4Hx6lPMSn7CPGM/aKm2vg3ijqPSeLgIQ==","shasum":"1c47d4352981e3d92c2476419a0e031fc892ebb0","tarball":"https://registry.npmjs.org/@daniadelapuenteveliz/sam-smith/-/sam-smith-1.0.1.tgz","fileCount":23,"unpackedSize":336460,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGp38+yVac2sVRoUpLGr8um0Cxa2qXXIMt9ltzlmaSe8AiASel8p1SGX1Oj++h0oZ+NN7d9Xwo/7SpVU3GqDUK5o9Q=="}]},"_npmUser":{"name":"daniadelapuenteveliz","email":"daniaignaciadelapuenteveliz@gmail.com"},"directories":{},"maintainers":[{"name":"daniadelapuenteveliz","email":"daniaignaciadelapuenteveliz@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sam-smith_1.0.1_1775969128188_0.9408952189302209"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-11T22:45:43.159Z","modified":"2026-04-12T04:45:28.502Z","1.0.0":"2026-04-11T22:45:43.443Z","1.0.1":"2026-04-12T04:45:28.348Z"},"bugs":{"url":"https://github.com/daniadelapuenteveliz/sam-smith-typescript/issues"},"author":{"name":"Dania Ignacia de la Puente Véliz"},"license":"MIT","homepage":"https://github.com/daniadelapuenteveliz/sam-smith-typescript#readme","keywords":["sam","lambda","serverless","aws","api-gateway","typescript","cognito"],"repository":{"type":"git","url":"git+https://github.com/daniadelapuenteveliz/sam-smith-typescript.git"},"description":"Helper to build serverless backends in AWS (SAM + Lambda + API Gateway)","maintainers":[{"name":"daniadelapuenteveliz","email":"daniaignaciadelapuenteveliz@gmail.com"}],"readme":"# sam-smith\n\nA CLI tool for scaffolding AWS SAM serverless projects with TypeScript, Lambda functions, API Gateway, and Cognito authentication.\n\n> **Requirements:** Node.js 20+\n\n## Installation\n\n```bash\nnpm install -g sam-smith\n```\n\n## Quick Start\n\nCreate a new serverless project:\n\n```bash\nnpx sam-smith\n```\n\nFollow the interactive prompts to configure your project.\n\n## Project Templates\n\nsam-smith offers three project templates:\n\n### 1. **Basic**\nSimple serverless API with Lambda and API Gateway.\n- Single Lambda function\n- API Gateway with one endpoint\n- No authentication\n\n### 2. **Basic Auth**\nAPI with Lambda Authorizer for custom authentication.\n- Lambda function\n- API Gateway endpoint\n- Lambda Authorizer function for request-based auth\n- Validates custom headers (e.g., API keys)\n\n### 3. **Cognito Auth**\nAPI with AWS Cognito authentication.\n- Lambda function\n- API Gateway endpoint\n- Cognito User Pool and User Pool Client\n- JWT-based authentication\n\n## Usage\n\n### Creating a Project\n\n```bash\nnpx sam-smith\n```\n\nYou'll be prompted for:\n- **Template type**: Choose from `basic`, `basic-auth`, or `cognito-auth`\n- **Project name**: Name of your project directory\n- **Environment**: Deployment environment (e.g., `dev`, `prod`)\n- **Architecture**: `x86_64` or `arm64`\n- **API Gateway name**: Name for your API Gateway\n- **Lambda function name**: Name of your Lambda function\n- **Timeout**: Lambda timeout in seconds\n\n### Environment Variables\n\nsam-smith uses **AWS Systems Manager (SSM) Parameter Store** to manage environment variables securely.\n\n- **Storage**: Variables are stored in SSM Parameter Store with the path `/sam-smith/{environment}/{functionName}/{variableName}`.\n- **Template**: The generated `template.yaml` automatically references these parameters and passes them to your Lambda functions.\n- **Local Development**: A `.env` file is created in your project root with `ENVIRONMENT={environment}`. You can add local overrides here.\n- **Management**: Use `npm run sam-smith:update` to easily add, update, or remove environment variables.\n\nFor Cognito Auth template, you'll also be prompted for:\n- **User Pool name**: Name for your Cognito User Pool\n\n### Generated Project Structure\n\n```\nyour-project/\n├── src/\n│   └── yourFunction/\n│       ├── handler.ts       # Lambda function code\n│       └── handler.test.ts  # Jest tests\n├── template.yaml             # SAM template\n├── samconfig.toml           # SAM configuration\n├── package.json\n├── tsconfig.json\n└── jest.config.js\n```\n\n## Available Commands\n\nOnce your project is created, navigate to the project directory and use these commands:\n\n### Build\n\nCompile TypeScript and prepare for deployment:\n\n```bash\nnpm run sam-smith:build\n```\n\n### Deploy\n\nDeploy to AWS:\n\n```bash\nnpm run sam-smith:deploy\n```\n\n### Local Development\n\nRun API locally (requires Docker):\n\n```bash\nnpm run sam-smith:start\n```\n\nRun on a custom port:\n\n```bash\nnpm run sam-smith:start -- -p 3001\n```\n\nTest your local endpoint:\n\n```bash\ncurl http://127.0.0.1:3000/hello\n```\n\n### Update Project\n\nManage your SAM project resources interactively:\n\n```bash\nnpm run sam-smith:update\n```\n\nThis allows you to:\n- **API Gateways**: Create, update, delete API Gateways and endpoints\n- **Lambda Functions**: Create, update, delete Lambda functions\n- **Layers**: Create and manage Lambda layers\n- **DynamoDB Tables**: Create and manage DynamoDB tables\n- **Authentication**: Add/remove Basic Auth or Cognito Auth\n- **User Pools**: Create user groups in Cognito User Pools\n- **Environment Variables**: Add, update, or remove environment variables\n\n### Run Tests\n\n```bash\nnpm test\n```\n\n### Generate Documentation\n\nGenerate OpenAPI/Swagger documentation:\n\n```bash\nnpx sam-smith doc\n```\n\n## Features\n\n### Resource Management\n\n- ✅ **API Gateways**: REST APIs with CORS support\n- ✅ **Lambda Functions**: TypeScript Lambda functions with esbuild\n- ✅ **Lambda Layers**: Shared code and dependencies\n- ✅ **DynamoDB Tables**: NoSQL database tables\n- ✅ **Environment Variables**: SSM Parameter Store integration\n\n### Authentication\n\n- ✅ **Basic Auth**: Lambda Authorizer with custom header validation\n- ✅ **Cognito Auth**: JWT-based authentication with User Pools\n- ✅ **User Groups**: Role-based access control with Cognito groups\n\n### Development\n\n- ✅ **TypeScript**: Full TypeScript support\n- ✅ **Testing**: Jest test framework included\n- ✅ **Local Testing**: Run API locally with SAM CLI\n- ✅ **Hot Reload**: TypeScript compilation on changes\n\n## Testing Cognito Authentication\n\nAfter deploying a Cognito-auth project:\n\n1. **Create a user and set password:**\n\n```bash\naws cognito-idp admin-set-user-password \\\n  --user-pool-id YOUR_USER_POOL_ID \\\n  --username testuser \\\n  --password MyPass123! \\\n  --permanent\n```\n\n2. **Get authentication token:**\n\n```bash\nTOKEN=$(aws cognito-idp initiate-auth \\\n  --auth-flow USER_PASSWORD_AUTH \\\n  --client-id YOUR_CLIENT_ID \\\n  --auth-parameters USERNAME=testuser,PASSWORD=MyPass123! \\\n  --query 'AuthenticationResult.IdToken' \\\n  --output text)\n```\n\n3. **Call your protected endpoint:**\n\n```bash\ncurl https://YOUR_API_ID.execute-api.us-east-1.amazonaws.com/default/hello \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n> **Note:** Cognito authentication only works when deployed to AWS, not in local development with `sam local`.\n\n## Example: Adding DynamoDB to Your Project\n\n```bash\nnpm run sam-smith:update\n# Select: DynamoDB Tables → create → Enter table details\n```\n\n## Example: Adding an Endpoint\n\n```bash\nnpm run sam-smith:update\n# Select: API Gateways → update → [Your API] → add endpoint\n# Enter: Method (GET/POST/etc.), Path, Lambda function\n```\n\n## AWS Requirements\n\n### Prerequisites\n\n- AWS CLI configured with appropriate credentials\n- AWS SAM CLI installed\n- Docker (for local development)\n\n### IAM Permissions\n\nTo use sam-smith, you need an AWS IAM user or role with the following permissions. All resources created by sam-smith use the `sam-smith-*` naming convention for easy identification and security scoping.\n\n#### Required IAM Policy\n\nCreate an IAM policy with the following JSON. **Important:** Replace `YOUR_ACCOUNT_ID` and `YOUR_REGION` with your actual AWS account ID and preferred region (e.g., `us-east-1`).\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"CloudFormationStack\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"cloudformation:CreateChangeSet\",\n                \"cloudformation:DescribeStacks\",\n                \"cloudformation:ListStacks\",\n                \"cloudformation:GetTemplateSummary\",\n                \"cloudformation:DescribeChangeSet\",\n                \"cloudformation:DescribeStackEvents\",\n                \"cloudformation:ExecuteChangeSet\"\n            ],\n            \"Resource\": [\n                \"arn:aws:cloudformation:YOUR_REGION:YOUR_ACCOUNT_ID:stack/aws-sam-cli-managed-default/*\",\n                \"arn:aws:cloudformation:YOUR_REGION:YOUR_ACCOUNT_ID:stack/sam-smith-*\"\n            ]\n        },\n        {\n            \"Sid\": \"CloudFormationTransform\",\n            \"Effect\": \"Allow\",\n            \"Action\": \"cloudformation:CreateChangeSet\",\n            \"Resource\": \"arn:aws:cloudformation:YOUR_REGION:aws:transform/Serverless-*\"\n        },\n        {\n            \"Sid\": \"S3DeploymentBucket\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"s3:PutObject\",\n                \"s3:GetObject\",\n                \"s3:DeleteObject\"\n            ],\n            \"Resource\": \"arn:aws:s3:::aws-sam-cli-managed-default-samclisourcebucket-*/*\"\n        },\n        {\n            \"Sid\": \"IAMRoles\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"iam:CreateRole\",\n                \"iam:DeleteRole\",\n                \"iam:GetRole\",\n                \"iam:PassRole\",\n                \"iam:AttachRolePolicy\",\n                \"iam:DetachRolePolicy\",\n                \"iam:PutRolePolicy\",\n                \"iam:DeleteRolePolicy\",\n                \"iam:TagRole\",\n                \"iam:UntagRole\",\n                \"iam:CreatePolicy\"\n            ],\n            \"Resource\": [\n                \"arn:aws:iam::YOUR_ACCOUNT_ID:role/sam-smith-*\",\n                \"arn:aws:iam::YOUR_ACCOUNT_ID:policy/sam-smith-*\"\n            ]\n        },\n        {\n            \"Sid\": \"SSMParameters\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"ssm:PutParameter\",\n                \"ssm:GetParameter\",\n                \"ssm:GetParameters\",\n                \"ssm:DeleteParameter\",\n                \"ssm:DescribeParameters\",\n                \"ssm:AddTagsToResource\",\n                \"ssm:RemoveTagsFromResource\"\n            ],\n            \"Resource\": [\n                \"arn:aws:ssm:YOUR_REGION:YOUR_ACCOUNT_ID:parameter/sam-smith*\",\n                \"arn:aws:ssm:YOUR_REGION:YOUR_ACCOUNT_ID:parameter/sam-smith-*\"\n            ]\n        },\n        {\n            \"Sid\": \"LambdaFunctions\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"lambda:CreateFunction\",\n                \"lambda:UpdateFunctionCode\",\n                \"lambda:UpdateFunctionConfiguration\",\n                \"lambda:DeleteFunction\",\n                \"lambda:GetFunction\",\n                \"lambda:TagResource\",\n                \"lambda:UntagResource\",\n                \"lambda:AddPermission\",\n                \"lambda:RemovePermission\",\n                \"lambda:PublishLayerVersion\",\n                \"lambda:GetLayerVersion\"\n            ],\n            \"Resource\": [\n                \"arn:aws:lambda:YOUR_REGION:YOUR_ACCOUNT_ID:function:sam-smith-*\",\n                \"arn:aws:lambda:YOUR_REGION:YOUR_ACCOUNT_ID:layer:sam-smith-*\"\n            ]\n        },\n        {\n            \"Sid\": \"CloudWatchLogs\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"logs:CreateLogGroup\",\n                \"logs:DeleteLogGroup\",\n                \"logs:DescribeLogGroups\",\n                \"logs:PutRetentionPolicy\"\n            ],\n            \"Resource\": \"arn:aws:logs:YOUR_REGION:YOUR_ACCOUNT_ID:log-group:/aws/lambda/sam-smith-*\"\n        },\n        {\n            \"Sid\": \"APIGateway\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"apigateway:POST\",\n                \"apigateway:PUT\",\n                \"apigateway:PATCH\",\n                \"apigateway:DELETE\",\n                \"apigateway:GET\"\n            ],\n            \"Resource\": \"arn:aws:apigateway:YOUR_REGION::/restapis*\"\n        },\n        {\n            \"Sid\": \"DynamoDB\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"dynamodb:DescribeTable\",\n                \"dynamodb:CreateTable\",\n                \"dynamodb:DeleteTable\",\n                \"dynamodb:UpdateTable\"\n            ],\n            \"Resource\": \"arn:aws:dynamodb:YOUR_REGION:YOUR_ACCOUNT_ID:table/sam-smith-*\"\n        },\n        {\n            \"Sid\": \"Cognito\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"cognito-idp:CreateUserPool\",\n                \"cognito-idp:CreateUserPoolClient\",\n                \"cognito-idp:DeleteUserPool\",\n                \"cognito-idp:DeleteUserPoolClient\",\n                \"cognito-idp:DescribeUserPool\",\n                \"cognito-idp:UpdateUserPool\",\n                \"cognito-idp:ListUserPools\",\n                \"cognito-idp:GetGroup\",\n                \"cognito-idp:CreateGroup\",\n                \"cognito-idp:DeleteGroup\"\n            ],\n            \"Resource\": \"arn:aws:cognito-idp:YOUR_REGION:YOUR_ACCOUNT_ID:userpool/*\"\n        }\n    ]\n}\n```\n\n#### Resource Breakdown\n\n| Service | Purpose | Resource Pattern |\n|---------|---------|------------------|\n| **CloudFormation** | Deploy and manage SAM stacks | `sam-smith-*` |\n| **S3** | Store deployment artifacts | SAM CLI managed bucket |\n| **IAM** | Lambda execution roles and policies | `sam-smith-*` |\n| **SSM Parameter Store** | Environment variable storage | `sam-smith*` and `sam-smith-*` |\n| **Lambda** | Function deployment and layers | `sam-smith-*` |\n| **CloudWatch Logs** | Function logging | `/aws/lambda/sam-smith-*` |\n| **API Gateway** | REST API endpoints | All REST APIs in region |\n| **DynamoDB** | Database tables | `sam-smith-*` |\n| **Cognito** | User authentication | All user pools |\n\n#### Security Best Practices\n\n- ✅ **Least Privilege**: Policy restricts resources to `sam-smith-*` pattern\n- ✅ **Resource Scoping**: All ARNs are scoped to your account and region\n- ✅ **Stack Naming**: All CloudFormation stacks use `sam-smith-` prefix\n- ⚠️ **API Gateway**: Permissions apply to all REST APIs (cannot be scoped by name pattern)\n- ⚠️ **Cognito**: Permissions apply to all user pools in the account\n\n\n```bash\nnpm test\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.","readmeFilename":"README.md"}