feat: add env.template support with type hint validation

Co-Authored-By: rlauer@blues.com <rlauer@blues.com>

Author: devin-ai-integration[bot]

docs/api.md

@@ -210,19 +210,94 @@ Perform an [env.default](#namespacenotecard_1_1env_1a6ff91175ae591e8a3a87c2a4ef9
 #### Returns
 string The result of the Notecard request.
 
-#### `public def `[`get`](#namespacenotecard_1_1env_1a28ed0423d0aff1d109371427139e0a73)`(card,name)` 
+#### `public def `[`get`](#namespacenotecard_1_1env_1a28ed0423d0aff1d109371427139e0a73)`(card,name,names,time)` 
 
 Perform an [env.get](#namespacenotecard_1_1env_1a28ed0423d0aff1d109371427139e0a73) request against a Notecard.
 
 #### Parameters
-* `card` The current Notecard object. 
+* `card` The current Notecard object.
+
+* `name` (optional) The name of an environment variable to get.
 
-* `name` The name of an environment variable to get.
+* `names` (optional) List of environment variable names to retrieve.
+
+* `time` (optional) UNIX epoch time to get variables modified after.
 
 #### Returns
+dict The result of the Notecard request containing either:
+* `text` Value of the requested variable if name was specified
+* `body` Object with name/value pairs if names was specified or if neither name nor names was specified
+* `time` UNIX epoch time of the last variable change
+
+Example request with single variable:
+```json
+{
+    "req": "env.get",
+    "name": "my_var"
+}
+```
+
+Example request with multiple variables:
+```json
+{
+    "req": "env.get",
+    "names": ["var1", "var2"]
+}
+```
+
+Example response for single variable:
+```json
+{
+    "text": "value1"
+}
+```
+
+Example response for multiple variables:
+```json
+{
+    "body": {
+        "var1": "value1",
+        "var2": "value2"
+    },
+    "time": 1609459200
+}
+```
+
+#### `public def `[`template`](#namespacenotecard_1_1env_1a10f5f4667d80f47674d1876df69b8e22)`(card,body)` 
+
+Perform an env.template request against a Notecard.
+
+#### Parameters
+* `card` The current Notecard object.
+
+* `body` (optional) Schema with variable names and type hints.
+  * Boolean: must be specified as true
+  * String: numeric string for max length (pre v3.2.1) or variable-length (v3.2.1+)
+  * Integer: 11-14, 18 for signed, 21-24 for unsigned
+  * Float: 12.1 (2-byte), 14.1 (4-byte), 18.1 (8-byte)
 
 #### Returns
-string The result of the Notecard request.
+dict The result of the Notecard request, including 'bytes' field indicating storage size.
+
+Example request:
+```json
+{
+    "req": "env.template",
+    "body": {
+        "active": true,
+        "name": "32",
+        "temperature": 14.1,
+        "counter": 12
+    }
+}
+```
+
+Example response:
+```json
+{
+    "bytes": 42
+}
+```
 
 #### `public def `[`modified`](#namespacenotecard_1_1env_1aa672554b72786c9ec1e5f76b3e11eb34)`(card)` 
 

notecard/env.py

@@ -34,19 +34,29 @@ def default(card, name=None, text=None):
 
 
 @validate_card_object
-def get(card, name=None):
+def get(card, name=None, names=None, time=None):
     """Perform an env.get request against a Notecard.
 
     Args:
         card (Notecard): The current Notecard object.
-        name (string): The name of an environment variable to get.
+        name (str, optional): The name of an environment variable to get.
+        names (list, optional): List of environment variable names to retrieve.
+        time (int, optional): UNIX epoch time to get variables modified after.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing either:
+            - text: Value of the requested variable if name was specified
+            - body: Object with name/value pairs if names was specified or
+                   if neither name nor names was specified
+            - time: UNIX epoch time of the last variable change
     """
     req = {"req": "env.get"}
     if name:
         req["name"] = name
+    if names:
+        req["names"] = names
+    if time is not None:
+        req["time"] = time
     return card.Transaction(req)
 
 
@@ -82,3 +92,31 @@ def set(card, name=None, text=None):
     if text:
         req["text"] = text
     return card.Transaction(req)
+
+
+@validate_card_object
+def template(card, body=None):
+    """Perform an env.template request against a Notecard.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        body (dict, optional): Schema with variable names and type hints.
+            Supported type hints:
+            - Boolean: true
+            - String: numeric string for max length (pre v3.2.1)
+            - Integer: 11-14, 18 (signed), 21-24 (unsigned)
+            - Float: 12.1 (2-byte), 14.1 (4-byte), 18.1 (8-byte)
+
+    Returns:
+        dict: The result of the Notecard request, including 'bytes' field
+            indicating storage size.
+
+    Raises:
+        ValueError: If type hints in body are invalid.
+    """
+    req = {"req": "env.template"}
+    if body is not None:
+        from .validators import validate_template_hints
+        validate_template_hints(body)
+        req["body"] = body
+    return card.Transaction(req)

notecard/validators.py

@@ -36,3 +36,36 @@ def wrap_validator(*args, **kwargs):
             return func(*args, **kwargs)
 
         return wrap_validator
+
+
+def validate_template_hints(body):
+    """Validate type hints in env.template body.
+
+    Args:
+        body (dict): Schema with variable names and type hints.
+
+    Raises:
+        ValueError: If type hints are invalid.
+    """
+    if not isinstance(body, dict):
+        raise ValueError("Template body must be a dictionary")
+
+    for key, value in body.items():
+        if isinstance(value, bool):
+            if value is not True:
+                raise ValueError(f"Boolean hint for {key} must be True")
+        elif isinstance(value, (int, float)):
+            valid_types = [
+                11, 12, 13, 14, 18,  # signed integers
+                21, 22, 23, 24,      # unsigned integers
+                12.1, 14.1, 18.1     # floats
+            ]
+            if value not in valid_types:
+                raise ValueError(f"Invalid numeric hint for {key}")
+        elif isinstance(value, str):
+            try:
+                int(value)  # pre v3.2.1 string length
+            except ValueError:
+                pass  # post v3.2.1 variable length strings
+        else:
+            raise ValueError(f"Invalid type hint for {key}")

test/fluent_api/test_env.py

@@ -15,6 +15,16 @@
             'env.get',
             {'name': 'my_var'}
         ),
+        (
+            env.get,
+            'env.get',
+            {'names': ['var1', 'var2']}
+        ),
+        (
+            env.get,
+            'env.get',
+            {'time': 1609459200}
+        ),
         (
             env.modified,
             'env.modified',

test/fluent_api/test_env_template.py

@@ -0,0 +1,99 @@
+"""Tests for env.template functionality."""
+from notecard import env
+
+
+def test_env_template_basic(run_fluent_api_notecard_api_mapping_test):
+    """Test env.template with no body parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {})
+
+
+def test_env_template_with_boolean(run_fluent_api_notecard_api_mapping_test):
+    """Test env.template with boolean type hint."""
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': {'my_bool': True}})
+
+
+def test_env_template_with_string_pre_321(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test string type hint in env.template.
+
+    For pre v3.2.1 format."""
+    body = {'my_string': '42'}
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_string_post_321(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test string type hint in env.template.
+
+    For post v3.2.1 format."""
+    body = {'my_string': 'variable'}
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_signed_integers(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test signed integer hints.
+
+    Covers all supported sizes."""
+    body = {
+        'int8': 11,    # 1 byte signed
+        'int16': 12,   # 2 byte signed
+        'int24': 13,   # 3 byte signed
+        'int32': 14,   # 4 byte signed
+        'int64': 18    # 8 byte signed
+    }
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_unsigned_integers(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test unsigned integer hints.
+
+    Covers all supported sizes."""
+    body = {
+        'uint8': 21,   # 1 byte unsigned
+        'uint16': 22,  # 2 byte unsigned
+        'uint24': 23,  # 3 byte unsigned
+        'uint32': 24   # 4 byte unsigned
+    }
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_floats(run_fluent_api_notecard_api_mapping_test):
+    """Test env.template with float type hints."""
+    body = {
+        'float16': 12.1,  # 2 byte float
+        'float32': 14.1,  # 4 byte float
+        'float64': 18.1   # 8 byte float
+    }
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_with_mixed_types(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test mixed type hints.
+
+    Tests bool, str, float, int."""
+    body = {
+        'active': True,
+        'name': '32',
+        'temperature': 14.1,
+        'counter': 12
+    }
+    run_fluent_api_notecard_api_mapping_test(
+        env.template, 'env.template', {'body': body})
+
+
+def test_env_template_response(card):
+    """Test env.template response contains bytes field."""
+    card.Transaction.return_value = {'bytes': 42}
+    response = env.template(card)
+    assert 'bytes' in response
+    assert isinstance(response['bytes'], int)