velocity-python 0.1.20__tar.gz → 0.1.22__tar.gz

{velocity_python-0.1.20/src/velocity_python.egg-info → velocity_python-0.1.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.20
+Version: 0.1.22
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.20 → velocity_python-0.1.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.20"
+version = "0.1.22"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.20 → velocity_python-0.1.22}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.20"
+__version__ = version = "0.1.22"
 
 import importlib as _importlib
 

{velocity_python-0.1.20 → velocity_python-0.1.22}/src/velocity/aws/__init__.py

@@ -28,6 +28,16 @@ _LAZY_ATTRS = {
     "initialize_build_environment": "velocity.aws.amplify_build",
     "run_backend_deployment": "velocity.aws.amplify_build",
     "update_lambda_layers_to_latest": "velocity.aws.amplify_build",
+    # S3 utilities
+    "generate_presigned_get": "velocity.aws.s3",
+    "generate_presigned_put": "velocity.aws.s3",
+    "list_client_files": "velocity.aws.s3",
+    "normalize_client_prefix": "velocity.aws.s3",
+    "CLIENT_FILES_BUCKET": "velocity.aws.s3",
+    "PUBLIC_ASSETS_BUCKET": "velocity.aws.s3",
+    "BACKOFFICE_BUCKET": "velocity.aws.s3",
+    "PRIVATE_BUCKETS": "velocity.aws.s3",
+    "ALLOWED_UPLOAD_BUCKETS": "velocity.aws.s3",
 }
 
 
@@ -47,4 +57,14 @@ __all__ = [
     "initialize_build_environment",
     "run_backend_deployment",
     "update_lambda_layers_to_latest",
+    # S3 utilities
+    "generate_presigned_get",
+    "generate_presigned_put",
+    "list_client_files",
+    "normalize_client_prefix",
+    "CLIENT_FILES_BUCKET",
+    "PUBLIC_ASSETS_BUCKET",
+    "BACKOFFICE_BUCKET",
+    "PRIVATE_BUCKETS",
+    "ALLOWED_UPLOAD_BUCKETS",
 ]

{velocity_python-0.1.20 → velocity_python-0.1.22}/src/velocity/aws/amplify_build.py

@@ -377,7 +377,7 @@ def set_cloudwatch_logging(
             f"arn:aws:lambda:{region}:{account_id}:function:LambdaCloudWatchNotification"
         ),
         "filterName": function_name,
-        "filterPattern": "?ERROR ?WARN ?EXCEPTION ?CRITICAL",
+        "filterPattern": "?error ?exception ?warning ?critical ?ERROR ?EXCEPTION ?WARN ?CRITICAL",
     }
     for _attempt in range(2):
         try:

velocity_python-0.1.22/src/velocity/aws/s3.py

@@ -0,0 +1,175 @@
+"""Centralized S3 utilities: presigned URL generation and private-file listing.
+
+Architectural principles enforced here
+---------------------------------------
+* All files in *private* buckets (e.g. ``caringcent.client.files``) MUST be
+  stored without a public ACL.  Access is granted exclusively through
+  time-limited presigned GET URLs generated by this module.
+* Direct browser-to-S3 uploads are supported via presigned PUT URLs so that
+  file bytes never pass through Lambda (avoids the 6 MB API Gateway payload
+  ceiling and reduces Lambda cost).
+* Public-asset buckets (``donate.resources``, ``backoffice.resources``) remain
+  unaffected by this module; they continue to use ``ACL: public-read`` when
+  uploaded via ``helpers.upload(public=True)``.
+
+Bucket constants
+-----------------
+Import and compare against these rather than hard-coding bucket names in
+Lambda handlers so a rename only needs to happen in one place.
+"""
+from __future__ import annotations
+
+import re
+import boto3
+
+# ---------------------------------------------------------------------------
+# Bucket name constants
+# ---------------------------------------------------------------------------
+
+CLIENT_FILES_BUCKET: str = "caringcent.client.files"
+"""Private bucket that stores per-client files (billing reports, uploads)."""
+
+PUBLIC_ASSETS_BUCKET: str = "donate.resources"
+"""Public bucket for images and form-builder assets embedded in donation forms."""
+
+BACKOFFICE_BUCKET: str = "backoffice.resources"
+"""Internal bucket for BackOffice admin assets (help videos, data-load ZIPs)."""
+
+# Buckets that must never be served with a public ACL.
+PRIVATE_BUCKETS: frozenset[str] = frozenset({CLIENT_FILES_BUCKET})
+
+# Buckets that are permitted as upload destinations from BackOffice.
+ALLOWED_UPLOAD_BUCKETS: frozenset[str] = frozenset(
+    {CLIENT_FILES_BUCKET, PUBLIC_ASSETS_BUCKET, BACKOFFICE_BUCKET}
+)
+
+
+# ---------------------------------------------------------------------------
+# Presigned URL helpers
+# ---------------------------------------------------------------------------
+
+def generate_presigned_get(
+    bucket: str,
+    key: str,
+    *,
+    expires_in: int = 3600,
+    filename: str | None = None,
+    content_type: str | None = None,
+) -> str:
+    """Return a presigned GET URL for a private S3 object.
+
+    Args:
+        bucket: S3 bucket name.
+        key: S3 object key.
+        expires_in: URL lifetime in seconds (default 1 hour).
+        filename: When provided the presigned URL includes a
+            ``Content-Disposition: attachment; filename="..."`` override so the
+            browser downloads the file under *filename* instead of navigating
+            to the raw key.  This also prevents the browser from navigating
+            away from the current SPA page.
+        content_type: Optional ``Content-Type`` override embedded in the
+            presigned URL query-string.
+
+    Returns:
+        A time-limited, signed HTTPS URL that grants GET access to the object.
+    """
+    params: dict = {"Bucket": bucket, "Key": key}
+    if filename:
+        params["ResponseContentDisposition"] = f'attachment; filename="{filename}"'
+    if content_type:
+        params["ResponseContentType"] = content_type
+    s3 = boto3.client("s3")
+    return s3.generate_presigned_url("get_object", Params=params, ExpiresIn=expires_in)
+
+
+def generate_presigned_put(
+    bucket: str,
+    key: str,
+    *,
+    content_type: str | None = None,
+    expires_in: int = 900,
+) -> dict:
+    """Return a presigned PUT URL for a direct browser-to-S3 upload.
+
+    Using this URL the browser PUTs the file body directly to S3, bypassing
+    Lambda entirely.  This removes the 6 MB API Gateway payload limit and
+    reduces Lambda invocation cost for large files.
+
+    Args:
+        bucket: S3 bucket name.
+        key: S3 object key for the uploaded file.
+        content_type: Optional MIME type.  When supplied the client **must**
+            send the same ``Content-Type`` header in the PUT request, otherwise
+            S3 rejects the upload with a 403.
+        expires_in: URL lifetime in seconds (default 15 minutes).
+
+    Returns:
+        dict with keys ``url`` (the presigned PUT URL), ``key``, and
+        ``bucket``.  Pass this dict back to the frontend; the browser calls
+        ``fetch(url, { method: 'PUT', body: file })`` to upload.
+    """
+    params: dict = {"Bucket": bucket, "Key": key}
+    if content_type:
+        params["ContentType"] = content_type
+    s3 = boto3.client("s3")
+    url = s3.generate_presigned_url("put_object", Params=params, ExpiresIn=expires_in)
+    return {"url": url, "key": key, "bucket": bucket}
+
+
+# ---------------------------------------------------------------------------
+# Object listing helpers
+# ---------------------------------------------------------------------------
+
+def normalize_client_prefix(client_id: str) -> str:
+    """Normalise *client_id* to the S3 key prefix used when storing files.
+
+    The convention (established by ``OnActionAdminUploadFiles``) is
+    ``lowercase + spaces → hyphens``, matching the existing
+    ``client_id.lower().replace(" ", "-")`` pattern.
+    """
+    return re.sub(r"\s+", "-", (client_id or "").strip().lower())
+
+
+def list_client_files(
+    bucket: str,
+    client_prefix: str,
+    *,
+    expires_in: int = 3600,
+) -> list[dict]:
+    """List non-empty objects under *client_prefix* and attach presigned URLs.
+
+    Zero-byte objects (S3 directory markers created by the console) are
+    silently skipped.
+
+    Each returned dict is the original S3 ``Contents`` entry enriched with:
+
+    * ``SignedUrl`` – presigned GET URL valid for *expires_in* seconds.
+    * ``Header`` – humanized sub-folder name (second-to-last key component),
+      used as the category label in :class:`S3DownloadsList`.
+    * ``FileName`` – the bare filename (last key component).
+
+    Args:
+        bucket: S3 bucket name.
+        client_prefix: Key prefix, typically the normalized client ID.
+        expires_in: Presigned URL lifetime in seconds (default 1 hour).
+
+    Returns:
+        List of enriched object dicts, empty if the prefix has no objects.
+    """
+    s3 = boto3.client("s3")
+    result = s3.list_objects_v2(Bucket=bucket, Prefix=client_prefix, MaxKeys=100)
+    enriched: list[dict] = []
+    for obj in result.get("Contents", []):
+        if obj.get("Size", 0) == 0:
+            continue  # skip directory-marker objects
+        key: str = obj["Key"]
+        parts = key.split("/")
+        obj["SignedUrl"] = generate_presigned_get(bucket, key, expires_in=expires_in)
+        obj["Header"] = (
+            parts[-2].replace("_", " ").replace("-", " ").title()
+            if len(parts) > 1
+            else ""
+        )
+        obj["FileName"] = parts[-1]
+        enriched.append(obj)
+    return enriched

{velocity_python-0.1.20 → velocity_python-0.1.22/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.20
+Version: 0.1.22
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.20 → velocity_python-0.1.22}/src/velocity_python.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ src/velocity/logging.py
 src/velocity/aws/__init__.py
 src/velocity/aws/amplify.py
 src/velocity/aws/amplify_build.py
+src/velocity/aws/s3.py
 src/velocity/aws/handlers/__init__.py
 src/velocity/aws/handlers/base_handler.py
 src/velocity/aws/handlers/context.py