nui-lambda-shared-utils 1.0.3__tar.gz → 1.1.1__tar.gz

nui_lambda_shared_utils-1.1.1/.markdownlint-cli2.yaml

@@ -0,0 +1,47 @@
+# Markdownlint configuration for nui-lambda-shared-utils
+# Extends workspace config with project-specific overrides
+
+config:
+  # Enable all rules by default
+  default: true
+
+  # MD013: Line length - disabled (technical docs need long lines for URLs/commands)
+  MD013: false
+
+  # MD033: Inline HTML - allowed (needed for complex formatting)
+  MD033: false
+
+  # MD036: No emphasis as heading - disabled (acceptable in planning docs)
+  MD036: false
+
+  # MD040: Fenced code language - disabled (not all code blocks need language tags)
+  MD040: false
+
+  # MD041: First line heading - disabled (docs may start with metadata)
+  MD041: false
+
+  # MD024: Multiple headings with same content - allowed with different levels
+  MD024:
+    siblings_only: true
+
+  # MD034: Bare URLs - allowed (sometimes intentional)
+  MD034: false
+
+  # MD046: Code block style - prefer fenced
+  MD046:
+    style: "fenced"
+
+  # MD060: Table column style - disabled (minor formatting preference)
+  MD060: false
+
+# File patterns to check
+globs:
+  - "**/*.md"
+
+# Exclusions
+ignores:
+  - "node_modules/**"
+  - "vendor/**"
+  - ".git/**"
+  - "venv/**"
+  - ".venv/**"

{nui_lambda_shared_utils-1.0.3 → nui_lambda_shared_utils-1.1.1}/CLAUDE.md

@@ -5,6 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Quick Links
 
 📚 **Documentation**: See [docs/README.md](docs/README.md) for comprehensive guides
+
 - [Quick Start Guide](docs/getting-started/quickstart.md) - Usage patterns and examples
 - [Configuration Guide](docs/getting-started/configuration.md) - Environment setup and credentials
 - [Slack Integration](docs/guides/slack-integration.md) - Messaging, formatting, and file uploads
@@ -15,6 +16,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Navigation Guide
 
 **Are you...**
+
 - 🆕 **New to this package?** → Start with [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)
 - 🔧 **Contributing code?** → See [Development Commands](#development-commands) below
 - 🧪 **Writing tests?** → See [docs/development/testing.md](docs/development/testing.md)
@@ -23,11 +25,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is `nui-lambda-shared-utils`, a Python package providing enterprise-grade utilities for AWS Lambda functions. It offers standardized integrations for Slack, Elasticsearch, database operations, CloudWatch metrics, and error handling patterns commonly used across NUI platform Lambda services.
+This is `nui-lambda-shared-utils`, a Python package providing production-ready utilities for AWS Lambda functions. Built and battle-tested on the NUI platform, it offers standardized integrations for Slack, Elasticsearch, database operations, CloudWatch metrics, and error handling patterns. The package is designed to be generic and configurable for any AWS Lambda environment.
 
 ## Architecture
 
 ### Core Module Structure
+
 - **Configuration System** (`config.py`) - Environment-aware configuration with AWS Secrets Manager integration
 - **Secrets Management** (`secrets_helper.py`) - Centralized credential handling with caching
 - **Slack Integration** (`slack_client.py`, `slack_formatter.py`) - Rich messaging, threading, and file uploads
@@ -35,25 +38,74 @@ This is `nui-lambda-shared-utils`, a Python package providing enterprise-grade u
 - **Database** (`db_client.py`) - Connection pooling with retry logic
 - **Metrics** (`cloudwatch_metrics.py`) - Batched CloudWatch publishing with decorators
 - **Error Handling** (`error_handler.py`) - Retry patterns with exponential backoff
-- **Timezone Utils** (`timezone.py`) - New Zealand timezone handling
+- **Timezone Utils** (`timezone.py`) - Timezone conversion and formatting utilities
 
 ### Optional Dependencies
+
 The package uses optional extras to minimize Lambda bundle size:
+
 - `elasticsearch` - Elasticsearch client and query builders
 - `database` - MySQL/PostgreSQL drivers
 - `slack` - Slack SDK
 - `all` - All integrations
 - `dev` - Development and testing tools
 
-### Slack Setup Module
+### Slack Workspace Automation
+
 The `slack_setup/` submodule provides automated Slack workspace configuration:
+
 - **Channel Creation** - Programmatic channel and permission setup
 - **Template System** - YAML-based channel definitions
-- **CLI Tool** - `nui-slack-setup` command for deployment
+- **CLI Tool** - `slack-channel-setup` command for automation
+- **Generic Design** - Adaptable for any Slack workspace, not NUI-specific
+
+## Design Principles
+
+### Keeping the Package Generic
+
+This package is intentionally designed to avoid vendor-specific assumptions:
+
+**✅ DO:**
+
+- Use configurable defaults (e.g., `currency` as required parameter)
+- Accept parameters for service-specific values (e.g., `service_name` in alerts)
+- Provide flexible configuration via environment variables or programmatic setup
+- Keep utility functions generic and reusable
+
+**❌ DON'T:**
+
+- Hardcode service names, currency codes, or business logic
+- Add domain-specific database query methods (use generic `query()`, `execute()` methods)
+- Create mapping dictionaries for specific organizations (emoji maps, status codes, etc.)
+- Assume specific table schemas or column names
+
+**Examples:**
+
+- ❌ Hardcoded organization-specific mappings and constants
+- ✅ Accept values as parameters or via configuration
+- ❌ Default values that assume specific geography/currency/timezone
+- ✅ Required parameters or configurable defaults
+- ❌ Database methods that assume specific table schemas
+- ✅ Generic query methods that accept SQL and parameters
+
+### When Adding New Features
+
+Before adding convenience methods or defaults:
+
+1. **Ask**: "Is this specific to NUI, or useful for any Lambda project?"
+2. **Check**: Could this be made configurable rather than hardcoded?
+3. **Test**: Can someone use this without NUI-specific knowledge?
+
+If a feature is NUI-specific:
+
+- Consider if it belongs in this shared package
+- Document it clearly as an example pattern users can adapt
+- Provide configuration options to override defaults
 
 ## Development Commands
 
 ### Environment Setup
+
 ```bash
 # Install package in development mode with all dependencies
 pip install -e .[dev]
@@ -90,6 +142,7 @@ pytest tests/test_slack_client.py -v
 ```
 
 ### Code Quality
+
 ```bash
 # Format code with Black (line length: 120)
 black nui_lambda_shared_utils/ tests/
@@ -102,6 +155,12 @@ mypy nui_lambda_shared_utils/ --config-file mypy.ini
 
 # Run linting (currently configured to use Black)
 black --check nui_lambda_shared_utils/
+
+# Lint markdown documentation
+npx markdownlint-cli2 '**/*.md'
+
+# Auto-fix markdown formatting issues
+npx markdownlint-cli2 --fix '**/*.md'
 ```
 
 ### Package Building and Publishing
@@ -122,7 +181,9 @@ python -m twine upload dist/*
 ## Configuration Patterns
 
 ### Environment Variables
+
 The package expects these environment variables for runtime configuration:
+
 - `ES_HOST` - Elasticsearch endpoint
 - `ES_CREDENTIALS_SECRET` - AWS secret name for ES credentials
 - `DB_CREDENTIALS_SECRET` - AWS secret name for database credentials  
@@ -130,7 +191,9 @@ The package expects these environment variables for runtime configuration:
 - `AWS_REGION` - AWS region for services
 
 ### AWS Secrets Format
+
 Secrets should follow standardized JSON structures:
+
 ```json
 // Elasticsearch
 {"host": "elastic:9200", "username": "user", "password": "pass"}
@@ -143,6 +206,7 @@ Secrets should follow standardized JSON structures:
 ```
 
 ### Programmatic Configuration
+
 ```python
 import nui_lambda_shared_utils as nui
 
@@ -160,6 +224,7 @@ nui.set_config(config)
 ## Common Usage Patterns
 
 For detailed usage examples and integration patterns, see:
+
 - **[Quick Start Guide](docs/getting-started/quickstart.md)** - Common usage patterns for all components
 - **[Slack Integration Guide](docs/guides/slack-integration.md)** - Slack messaging, blocks, threading, and file uploads
 - **[Configuration Guide](docs/getting-started/configuration.md)** - Environment setup and AWS Secrets integration
@@ -187,43 +252,88 @@ def critical_operation():
 ## Testing Strategy
 
 ### Test Categories (pytest markers)
+
 - `@pytest.mark.unit` - Fast unit tests with mocking
 - `@pytest.mark.integration` - Tests requiring AWS services
 - `@pytest.mark.slow` - Long-running tests
 
 ### AWS Testing
+
 Integration tests use `moto` for AWS service mocking. Some tests require real AWS credentials for full integration testing.
 
 ### Test Structure
-```
+
+```text
 tests/
 ├── test_<module>.py     # Main module tests
 ├── conftest.py         # Shared fixtures
 └── fixtures/           # Test data files
 ```
 
+## Contribution Guidelines
+
+### Pull Request Checklist
+
+Before submitting PRs, ensure:
+
+- [ ] **No hardcoded organization-specific values** (service names, currencies, business logic)
+- [ ] **Configuration options** provided for any defaults
+- [ ] **Tests pass** with `pytest --cov`
+- [ ] **Code formatted** with Black (`black nui_lambda_shared_utils/ tests/`)
+- [ ] **Type hints** included for public APIs
+- [ ] **Documentation updated** in docs/ for new features
+- [ ] **Generic naming** - avoid organization-specific terminology in public APIs
+
+### Code Review Focus Areas
+
+Reviewers should check for:
+
+- Generic utility patterns vs vendor-specific code
+- Configurable defaults rather than hardcoded values
+- Clear documentation of any platform assumptions
+- Reusability across different AWS Lambda projects
+
 ## Package Distribution
 
 ### Version Management
+
 Version is defined in both `setup.py` and `pyproject.toml` and should be kept in sync. The package follows semantic versioning.
 
 ### PyPI Publishing
+
 The package is published to PyPI as `nui-lambda-shared-utils` with GitHub Actions automation for releases.
 
 ### CLI Tools
-The package provides `nui-slack-setup` CLI tool for Slack workspace configuration.
+
+The package provides `slack-channel-setup` CLI tool for automating Slack workspace channel creation and configuration from YAML files. This is a generic tool useful for any team managing Slack workspaces.
+
+**Usage:**
+
+```bash
+# Create channels from YAML config
+slack-channel-setup --config channels.yaml
+
+# Check which channels exist
+slack-channel-setup --config channels.yaml --check-only
+
+# Generate environment variables
+slack-channel-setup --config channels.yaml --output channels.env --output-format env
+```
 
 ## AWS Lambda Integration
 
 ### Bundle Size Optimization
+
 - Use specific extras (`[slack]`, `[elasticsearch]`) rather than `[all]`
 - Optional imports prevent failure if dependencies aren't installed
 - Core utilities work without optional dependencies
 
 ### Lambda Layer Usage
+
 The package is designed to work well in Lambda layers for sharing across multiple functions.
 
 ### Environment Integration
+
 - Automatic AWS region detection
 - Secrets Manager integration with credential caching
 - CloudWatch metrics with proper dimensions
@@ -245,4 +355,4 @@ This project follows a clear documentation structure:
 configuration examples, and integration guides that complement these development instructions.
 
 **For new package users**: Start with [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)
-for working code examples and common patterns.
+for working code examples and common patterns.

{nui_lambda_shared_utils-1.0.3 → nui_lambda_shared_utils-1.1.1}/CONTRIBUTING.md

@@ -14,18 +14,21 @@ We welcome contributions to the NUI Lambda Shared Utilities project! This docume
 
 1. Fork the repository on GitHub
 2. Clone your fork locally:
+
    ```bash
    git clone https://github.com/your-username/nui-lambda-shared-utils.git
    cd nui-lambda-shared-utils
    ```
 
 3. Create a virtual environment:
+
    ```bash
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```
 
 4. Install development dependencies:
+
    ```bash
    pip install -e .[dev]
    ```
@@ -74,6 +77,7 @@ make lint  # If Makefile exists
 ### Submitting Changes
 
 1. Create a new branch for your feature/fix:
+
    ```bash
    git checkout -b feature/your-feature-name
    ```
@@ -85,11 +89,13 @@ make lint  # If Makefile exists
    - Documentation is updated
 
 3. Commit your changes:
+
    ```bash
    git commit -m "Add: brief description of your changes"
    ```
 
 4. Push to your fork:
+
    ```bash
    git push origin feature/your-feature-name
    ```
@@ -101,7 +107,6 @@ make lint  # If Makefile exists
 - **Title**: Use a clear, descriptive title
 - **Description**: Explain what your changes do and why
 - **Testing**: Include information about how you tested your changes
-- **Breaking Changes**: Clearly mark any breaking changes
 
 ### Commit Message Format
 
@@ -115,6 +120,7 @@ Use conventional commits format:
 - `chore:` for maintenance tasks
 
 Examples:
+
 - `feat: add retry decorator for database operations`
 - `fix: handle missing environment variables gracefully`
 - `docs: update configuration examples in README`
@@ -185,6 +191,7 @@ class MyUtility:
 - Use `test_<functionality>_<condition>_<expected_result>` pattern
 
 Example:
+
 ```python
 class TestSlackClient:
     def test_send_message_success_returns_true(self):
@@ -242,6 +249,7 @@ def example_function(param1: str, param2: Optional[int] = None) -> Dict[str, Any
 ### README Updates
 
 When adding new functionality, update the README.md with:
+
 - Usage examples
 - Configuration options
 - Any new dependencies
@@ -274,8 +282,9 @@ By contributing to this project, you agree that your contributions will be licen
 ## Questions?
 
 If you have questions about contributing, please:
+
 - Open an issue with the "question" label
 - Check the existing documentation
 - Look at similar implementations in the codebase
 
-Thank you for contributing! 🎉
+Thank you for contributing! 🎉

{nui_lambda_shared_utils-1.0.3 → nui_lambda_shared_utils-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-lambda-shared-utils
-Version: 1.0.3
+Version: 1.1.1
 Summary: Enterprise-grade utilities for AWS Lambda functions with Slack, Elasticsearch, and monitoring integrations
 Home-page: https://github.com/nuimarkets/nui-lambda-shared-utils
 Author: NUI Markets
@@ -38,11 +38,16 @@ Requires-Dist: pymysql>=1.0.0; extra == "database"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "database"
 Provides-Extra: slack
 Requires-Dist: slack-sdk>=3.19.0; extra == "slack"
+Provides-Extra: powertools
+Requires-Dist: aws-lambda-powertools<4.0.0,>=3.6.0; extra == "powertools"
+Requires-Dist: coloredlogs>=15.0; extra == "powertools"
 Provides-Extra: all
 Requires-Dist: elasticsearch<8.0.0,>=7.17.0; extra == "all"
 Requires-Dist: pymysql>=1.0.0; extra == "all"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
 Requires-Dist: slack-sdk>=3.19.0; extra == "all"
+Requires-Dist: aws-lambda-powertools<4.0.0,>=3.6.0; extra == "all"
+Requires-Dist: coloredlogs>=15.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -64,10 +69,11 @@ Dynamic: requires-python
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Enterprise-grade utilities for AWS Lambda functions with Slack, Elasticsearch, and monitoring integrations. This package provides standardized, production-ready patterns for common serverless operations while maintaining flexibility and configurability.
+Production-ready utilities for AWS Lambda functions with Slack, Elasticsearch, database, and monitoring integrations. Built and battle-tested on the NUI platform, this package provides standardized patterns for common serverless operations with sensible defaults that can be configured for any AWS environment.
 
 ## Table of Contents
 
+- [Who This Package Is For](#who-this-package-is-for)
 - [Key Features](#key-features)
 - [Documentation](#documentation)
 - [Quick Start](#quick-start)
@@ -79,8 +85,15 @@ Enterprise-grade utilities for AWS Lambda functions with Slack, Elasticsearch, a
 - [Documentation & Support](#documentation--support)
 - [License](#license)
 
+## Who This Package Is For
+
+**NUI Team**: Drop-in utilities with NUI platform defaults pre-configured. Handles common patterns like Slack notifications, Elasticsearch logging, database connections, and CloudWatch metrics out of the box.
+
+**External Teams**: Solid AWS Lambda patterns for serverless operations. Default configurations reflect NUI conventions (Elasticsearch index patterns, AWS Secrets Manager naming, Slack workspace structure) but are fully overridable via environment variables or programmatic configuration. Consider this package as production-tested reference implementations that you can adapt to your infrastructure.
+
 ## Key Features
 
+- **AWS Powertools Integration** - Standardized logging, metrics, and error handling for Lambda functions
 - **AWS Secrets Manager Integration** - Secure credential management with caching
 - **Slack Messaging** - Rich formatting, threading, file uploads, and channel management
 - **Elasticsearch Operations** - Query builders, index management, and health monitoring
@@ -102,6 +115,12 @@ Enterprise-grade utilities for AWS Lambda functions with Slack, Elasticsearch, a
 
 **Complete documentation**: See [docs/](docs/README.md) for all guides and references.
 
+**Component Guides:**
+
+- **[AWS Powertools Integration Guide](docs/guides/powertools-integration.md)** - Logging, metrics, error handling
+- **[Slack Integration Guide](docs/guides/slack-integration.md)** - Messaging, blocks, threading, files
+- **[Testing Guide](docs/development/testing.md)** - Test strategies and coverage
+
 ## Quick Start
 
 ### Installation
@@ -111,6 +130,7 @@ pip install nui-lambda-shared-utils
 
 # With specific extras for optional dependencies
 pip install nui-lambda-shared-utils[all]          # All integrations
+pip install nui-lambda-shared-utils[powertools]   # AWS Powertools only
 pip install nui-lambda-shared-utils[slack]        # Slack only
 pip install nui-lambda-shared-utils[elasticsearch] # Elasticsearch only
 pip install nui-lambda-shared-utils[database]     # Database only
@@ -166,6 +186,36 @@ slack_creds = get_slack_credentials()  # Uses configured secret name
 
 **[→ See full secrets management guide](docs/getting-started/configuration.md#aws-secrets-manager)**
 
+### AWS Powertools Integration
+
+```python
+from nui_lambda_shared_utils import get_powertools_logger, powertools_handler
+
+# Create logger with Elasticsearch-compatible formatting
+logger = get_powertools_logger("my-service", level="INFO")
+
+# Decorate Lambda handler with logging, metrics, and error handling
+@powertools_handler(
+    service_name="my-service",
+    metrics_namespace="MyApp/Service",
+    slack_alert_channel="#production-alerts"
+)
+@logger.inject_lambda_context
+def lambda_handler(event, context):
+    logger.info("Processing event", extra={"event_id": event.get("id")})
+    return {"statusCode": 200, "body": "Success"}
+```
+
+**Features:**
+
+- ✅ Elasticsearch-compatible timestamps (`2025-01-18T04:39:27.788Z`)
+- ✅ Automatic Lambda context injection (function name, request ID, cold start)
+- ✅ CloudWatch metrics publishing
+- ✅ Slack error alerts with graceful degradation
+- ✅ Local development with colored logs
+
+**[→ See comprehensive Powertools integration guide](docs/guides/powertools-integration.md)**
+
 ### Slack Integration
 
 ```python
@@ -276,11 +326,13 @@ This package requires AWS Secrets Manager for credential storage and IAM permiss
 ### Quick Reference
 
 **Secrets Manager** - Store credentials as JSON:
+
 - Elasticsearch: `{"host": "...", "username": "...", "password": "..."}`
 - Database: `{"host": "...", "port": 3306, "username": "...", "password": "...", "database": "..."}`
 - Slack: `{"bot_token": "xoxb-...", "webhook_url": "..."}`
 
 **IAM Permissions** - Lambda execution role needs:
+
 - `secretsmanager:GetSecretValue` for credential access
 - `cloudwatch:PutMetricData` for metrics publishing
 
@@ -307,15 +359,41 @@ pytest -m integration    # Integration tests (requires AWS)
 
 ## Contributing
 
+We welcome contributions! This package currently supports MySQL/PostgreSQL, Elasticsearch, Slack, and core AWS services (Secrets Manager, CloudWatch). **We're open to expanding support for additional databases (MongoDB, DynamoDB, etc.) and AWS services (SQS, SNS, EventBridge, etc.).**
+
+### How to Contribute
+
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
 3. Commit your changes (`git commit -m 'Add amazing feature'`)
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
+### Contribution Ideas
+
+- **Database integrations**: MongoDB, DynamoDB, Redis, Cassandra
+- **AWS services**: SQS, SNS, EventBridge, Step Functions, S3, SES
+- **Messaging platforms**: Microsoft Teams, Discord, PagerDuty
+- **Monitoring**: Datadog, New Relic, Prometheus exporters
+- **Search engines**: OpenSearch, Algolia, Typesense
+- **CLI enhancements**: Additional automation commands for common workflows
+
+See our [development guide](docs/development/testing.md) for testing patterns and architecture guidelines.
+
+### Built-in CLI Tools
+
+The package includes `slack-channel-setup` - a CLI tool for automating Slack workspace channel creation from YAML configuration files. This generic tool works with any Slack workspace and can be used independently of Lambda functions.
+
+```bash
+# Install and use
+pip install nui-lambda-shared-utils[slack]
+slack-channel-setup --config channels.yaml
+```
+
 ## Documentation & Support
 
 ### 📚 Documentation
+
 - **[Complete Documentation](docs/README.md)** - Comprehensive guides and references
 - **[Quick Start Guide](docs/getting-started/quickstart.md)** - Get up and running fast
 - **[Configuration Guide](docs/getting-started/configuration.md)** - Setup and AWS integration
@@ -323,12 +401,14 @@ pytest -m integration    # Integration tests (requires AWS)
 - **[Testing Guide](docs/development/testing.md)** - Test strategies and coverage
 
 ### 🔗 Links
+
 - **GitHub Repository**: https://github.com/nuimarkets/nui-lambda-shared-utils
 - **Issue Tracker**: https://github.com/nuimarkets/nui-lambda-shared-utils/issues
 - **PyPI Package**: https://pypi.org/project/nui-lambda-shared-utils/
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
 ### 💬 Support
+
 - **Bug Reports**: [GitHub Issues](https://github.com/nuimarkets/nui-lambda-shared-utils/issues)
 - **Feature Requests**: [GitHub Issues](https://github.com/nuimarkets/nui-lambda-shared-utils/issues)
 - **Questions**: Check [docs/](docs/README.md) first, then open an issue
@@ -339,5 +419,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## About NUI Markets
 
-NUI Markets is a technology company focused on building innovative trading and marketplace platforms. This package represents our commitment to open-source tooling and enterprise-grade infrastructure patterns.
-
+NUI Markets is a technology company focused on building innovative trading and marketplace platforms. This package represents our commitment to open-source tooling and production-grade infrastructure patterns for AWS Lambda development.