fix: address confirmed review findings on submit

Author: ShubhamBisht-Photon

src/photon/_transport.py

@@ -7,7 +7,7 @@
 Classification reads the response **body** before the status code, because the API
 puts the real outcome in the body's ``message``: a document that is still
 processing comes back as an HTTP 200, and several genuine failures come back as
-403. See ``plans/API-REFERENCE.md`` for the observed responses.
+403. See the official API docs (apidocs.photoncommerce.com) for the responses.
 """
 
 from __future__ import annotations

src/photon/client.py

@@ -43,8 +43,13 @@
 # actual file type.
 _FILE_FIELD = "pdf"
 
+# Filename sent for raw bytes and unnamed file objects. The API recognises file
+# types by extension, so the upload must carry one; callers whose content is not
+# a PDF should pass a path or a named file object instead.
+_DEFAULT_FILENAME = "upload.pdf"
+
 _SUBACCOUNT_MAX_LEN = 50
-_SUBACCOUNT_RE = re.compile(r"^[A-Za-z0-9-]+$")
+_SUBACCOUNT_RE = re.compile(r"[A-Za-z0-9-]+")
 
 
 class PhotonClient:
@@ -142,7 +147,10 @@ def submit(
         Args:
             document: The document to upload — a path, an open binary file
                 object, or raw bytes. A path is opened and closed by the
-                client; a file object is read as-is and left open.
+                client; a file object is read as-is and left open. The API
+                recognises file types by filename extension, so raw bytes and
+                unnamed file objects are uploaded as ``upload.pdf``; for other
+                file types, pass a path or a file object with a ``.name``.
             doctype: What kind of document this is; the API defaults to
                 invoice. Any string is passed through, so doctypes newer than
                 this SDK still work.
@@ -190,12 +198,12 @@ def submit(
         with contextlib.ExitStack() as cleanup:
             files: Any = None
             if isinstance(document, bytes):
-                files = {_FILE_FIELD: document}
+                files = {_FILE_FIELD: (_DEFAULT_FILENAME, document)}
             elif isinstance(document, (str, os.PathLike)):
                 handle = cleanup.enter_context(open(document, "rb"))
                 files = {_FILE_FIELD: (os.path.basename(os.fspath(document)), handle)}
             elif document is not None:
-                files = {_FILE_FIELD: document}
+                files = {_FILE_FIELD: (_filename_for(document), document)}
 
             body = self._transport.request_json(
                 "POST", SUBMIT_PATH, params=params, files=files
@@ -216,8 +224,7 @@ def retrieve(self, photon_key: str) -> dict[str, Any]:
 
         Raises:
             ValueError: ``photon_key`` is empty — checked before any I/O.
-            NotReadyError: The document is still being processed; retry later,
-                or let ``extract()`` (Week 3) poll for you.
+            NotReadyError: The document is still being processed; retry later.
             APIError: The response reported success but carried no ``data``
                 object.
             PhotonError: See :meth:`Transport.request_json` for the rest of
@@ -265,5 +272,21 @@ def __repr__(self) -> str:
         )
 
 
+def _filename_for(document: IO[bytes]) -> str:
+    """The filename to upload a file object under.
+
+    The API recognises file types by the uploaded filename's extension, so an
+    unnamed stream (``BytesIO``, a pipe, a fd-opened file) gets the default
+    rather than httpx's extensionless fallback.
+    """
+    name = getattr(document, "name", None)
+    if isinstance(name, str) and os.path.basename(name):
+        return os.path.basename(name)
+    return _DEFAULT_FILENAME
+
+
 def _is_valid_subaccount(subaccount: str) -> bool:
-    return len(subaccount) <= _SUBACCOUNT_MAX_LEN and bool(_SUBACCOUNT_RE.match(subaccount))
+    # fullmatch, not match: with match, "$" would accept a trailing newline.
+    return len(subaccount) <= _SUBACCOUNT_MAX_LEN and bool(
+        _SUBACCOUNT_RE.fullmatch(subaccount)
+    )

tests/test_submit.py

@@ -1,7 +1,7 @@
 """Tests for PhotonClient.submit: input modes, validation, and the Submission model.
 
-The API is stubbed with respx; the submit response shape comes from
-``plans/API-REFERENCE.md``.
+The API is stubbed with respx; the submit response shape comes from the
+official API docs (apidocs.photoncommerce.com).
 """
 
 from __future__ import annotations
@@ -78,7 +78,9 @@ def test_path_input_uploads_multipart_pdf_field(
     assert submission.doc_path == "uploads/2026/invoice-abc.pdf"
 
 
-def test_file_object_input_is_uploaded_and_left_open(client: PhotonClient) -> None:
+def test_unnamed_file_object_is_uploaded_with_an_extension_and_left_open(
+    client: PhotonClient,
+) -> None:
     handle = io.BytesIO(PDF_BYTES)
 
     with respx.mock(base_url=BASE_URL) as mock:
@@ -87,18 +89,36 @@ def test_file_object_input_is_uploaded_and_left_open(client: PhotonClient) -> No
 
     request = route.calls.last.request
     assert b'name="pdf"' in request.content
+    # The API recognises file types by extension, so an unnamed stream must not
+    # go out under httpx's extensionless fallback name.
+    assert b'filename="upload.pdf"' in request.content
     assert PDF_BYTES in request.content
     assert not handle.closed
 
 
-def test_bytes_input_is_uploaded(client: PhotonClient) -> None:
+def test_named_file_object_keeps_its_own_filename(
+    tmp_path: Path, client: PhotonClient
+) -> None:
+    document = tmp_path / "receipt.png"
+    document.write_bytes(PDF_BYTES)
+
+    with respx.mock(base_url=BASE_URL) as mock:
+        route = mock_submit(mock)
+        with document.open("rb") as handle:
+            client.submit(handle)
+
+    assert b'filename="receipt.png"' in route.calls.last.request.content
+
+
+def test_bytes_input_is_uploaded_with_an_extension(client: PhotonClient) -> None:
     with respx.mock(base_url=BASE_URL) as mock:
         route = mock_submit(mock)
         client.submit(PDF_BYTES)
 
     request = route.calls.last.request
     assert request.headers["content-type"].startswith("multipart/form-data")
     assert b'name="pdf"' in request.content
+    assert b'filename="upload.pdf"' in request.content
     assert PDF_BYTES in request.content
 
 
@@ -178,7 +198,7 @@ def test_both_document_and_url_is_a_value_error(client: PhotonClient) -> None:
 
 @pytest.mark.parametrize(
     "subaccount",
-    ["a" * 51, "under_score", "has space", "", "email@nope", "slash/nope"],
+    ["a" * 51, "under_score", "has space", "", "email@nope", "slash/nope", "team-1\n"],
 )
 def test_invalid_subaccount_is_a_value_error(client: PhotonClient, subaccount: str) -> None:
     with respx.mock(base_url=BASE_URL) as mock, pytest.raises(ValueError, match="subaccount"):

tests/test_transport.py

@@ -1,8 +1,8 @@
 """Tests for the HTTP transport: headers, response classification, lifecycle.
 
 The API is stubbed with respx, so these assert the SDK's behaviour against the
-responses recorded in ``plans/API-REFERENCE.md`` — including the ones that report
-failure with an HTTP 200.
+responses shown in the official API docs (apidocs.photoncommerce.com) — including
+the ones that report failure with an HTTP 200.
 """
 
 from __future__ import annotations