release: 2.3.3-rc2

[stainless-app]

Automated Release PR

2.3.3-rc2 (2025-12-18)

Full Changelog: v2.3.3-rc1...v2.3.3-rc2

Bug Fixes

• types: allow pyright to infer TypedDict types within SequenceNotStr (d1f6535)
• use async_to_httpx_files in patch method (a6fbc3c)

Chores

• add missing docstrings (a3c938c)
• docs: use environment variables for authentication in code snippets (534af15)
• internal: add --fix argument to lint script (4b3b067)
• internal: add missing files argument to base client (9672ca2)
• speedup initial import (4ae973c)
• update lockfile (abd7b3d)

---

This pull request is managed by Stainless's GitHub App.

The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.

For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.

🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions

[pullrequest]

HackerOne Code Security Review

🟢 Scan Complete: 5 Issue(s)
🟢 Validation Complete: Any Issues detected were validated by one of our engineers. None were determined to require immediate action.

Here's how the code changes were interpreted and info about the tools used for scanning.

📖 Summary of Changes

The update involves a minor release candidate revision (2.3.3-rc2) with documentation improvements across multiple files. Key changes include added docstrings for various classes, type-related bug fixes, and minor updates to authentication examples. Dependency lockfiles were also updated with package version bumps. The modifications focus on enhancing code documentation and maintaining library consistency.

File	Summary
.release-please-manifest.json	The version number in the JSON file has been updated from "2.3.3-rc1" to "2.3.3-rc2", indicating a release candidate update.
CHANGELOG.md	The changelog update adds a new version 2.3.3-rc2 with minor changes, including a type-related bug fix for pyright, added docstrings, and documentation updates for environment variable authentication.
README.md	The primary change is the addition of an environment variable check in the aiohttp example, using os.environ.get("WRITER_API_KEY") instead of hardcoding the API key. This provides a more secure and flexible approach to authentication.
pyproject.toml	The version number was updated from "2.3.3-rc1" to "2.3.3-rc2" in the project metadata section. No other significant changes were observed in the file.
requirements-dev.lock	The lockfile was updated with version bumps for multiple dependencies, including aiohttp, pydantic, pytest, and others. Some new dependencies like backports-asyncio-runner and humanize were added, while the overall structure remains consistent.
requirements.lock	The lockfile shows updates to various package versions, including aiohttp from 3.12.8 to 3.13.2, aiosignal from 1.3.2 to 1.4.0, and certifi from 2023.7.22 to 2025.11.12, with minor version changes to other dependencies.
src/writerai/_types.py	The changes involve modifying the SequenceNotStr protocol in the type checking section, specifically removing the index() and count() methods to improve type inference for TypedDict types when used in lists.
src/writerai/_version.py	The version number was updated from "2.3.3-rc1" to "2.3.3-rc2" in the version variable, indicating a minor release candidate revision.
src/writerai/types/application_list_response.py	The changes involve adding descriptive docstrings to several classes, providing more context about their purpose and configuration. The docstrings clarify the role of input option classes and provide additional explanation for input-related models.
src/writerai/types/application_retrieve_response.py	The changes involve adding descriptive docstrings to several classes, providing more context about their purpose and configuration. The docstrings clarify the role of each class and its attributes without altering the underlying code structure or functionality.
src/writerai/types/chat_chat_params.py	Minor documentation updates for several classes, including added docstrings for MessageContentMixedContentTextFragment, MessageContentMixedContentImageFragment, ResponseFormat, and StreamOptions. No significant structural changes observed.
src/writerai/types/chat_completion_chunk.py	The primary change is the addition of a docstring to the ChoiceDelta class, describing it as "A chat completion delta generated by streamed model responses." This docstring was previously absent in the old version of the file.
src/writerai/types/chat_completion_message.py	The file's class docstring for ChatCompletionMessage was updated with a new note about deprecation for streaming and a recommendation to use delta instead.
src/writerai/types/chat_completion_usage.py	A docstring was added to the ChatCompletionUsage class, providing a brief explanation of the class's purpose and noting that Knowledge Graph tool usage is not included in the usage information.
src/writerai/types/graph.py	The only change is a minor modification to the docstring for the FileStatus class, which now reads "The processing status of files in the Knowledge Graph" instead of the previous description.
src/writerai/types/graph_create_response.py	The only change is a minor reordering of the docstring for the URLStatus class, moving the class-level docstring before the status attribute's docstring, with no substantive content modification.
src/writerai/types/graph_question_params.py	Added a docstring to the QueryConfig class describing it as a configuration for Knowledge Graph queries. No other significant changes were observed in the file.
src/writerai/types/graph_update_response.py	The only change is a minor reordering of the docstring for the URLStatus class, moving the class-level docstring before the status attribute's docstring without altering the content or meaning.
src/writerai/types/question.py	The changes involve adding more descriptive docstrings to each class, providing clearer explanations of their purpose and contents. The structure and functionality of the code remain unchanged, with only documentation improvements.
src/writerai/types/shared/function_definition.py	The file's class docstring was updated to describe FunctionDefinition as "A tool that uses a custom function" instead of the previous empty docstring.
src/writerai/types/shared/graph_data.py	Added descriptive docstrings to each class, providing more context about their purpose and role in the Knowledge Graph system. The core structure and attributes of the classes remain unchanged.
src/writerai/types/shared/logprobs_token.py	Added a docstring to the TopLogprob class describing it as an array of mappings for tokens and their top log probabilities, providing a brief explanatory context for the class.
src/writerai/types/shared/source.py	The file's class docstring was updated to provide a more descriptive explanation of the Source class, changing from an empty description to a concise summary about the class representing a source snippet from Knowledge Graph content.
src/writerai/types/shared/tool_param.py	Minor documentation updates across multiple tool classes, including added docstrings for some classes and a note about non-streaming behavior for the TranslationTool. No significant structural or functional changes were observed.
src/writerai/types/shared_params/function_definition.py	The main change is the addition of a class-level docstring for FunctionDefinition, describing it as "A tool that uses a custom function" while maintaining the existing structure and attributes of the class.
src/writerai/types/shared_params/graph_data.py	The changes involve adding descriptive docstrings to several classes, providing more context about their purpose and contents. The added docstrings clarify the roles of ReferencesFile, ReferencesWeb, References, and Subquery classes without altering their underlying structure.
src/writerai/types/shared_params/source.py	The file's class docstring for Source was updated to provide a more descriptive explanation of the Source type, changing from an unspecified description to "A source snippet containing text and fileId from Knowledge Graph content."
src/writerai/types/shared_params/tool_param.py	Minor documentation changes in class descriptions and docstrings, including added note about translation tool not streaming results and slight reorganization of class-level documentation for several tool-related classes.
src/writerai/types/vision_analyze_params.py	The changes include adding a descriptive docstring to the Variable class explaining file requirements and referencing the Files API, while maintaining the existing structure and content of the file.

ℹ️ Issues Detected

NOTE: These may not require action!

Below are unvalidated results from the Analysis Tools that ran during the latest scan for transparency. We investigate each of these for accuracy and relevance before surfacing them as a potential problem.

How will I know if something is a problem?
When validation completes, any concerns that warrant attention prior to merge will be posted as inline comments. These will show up in 2 ways:

• Expert review (most cases): Issues will be posted by experts who manually reviewed and validated them. These are real HackerOne engineers (not bots) reviewing through an integrated IDE-like tool. You can communicate with them like any other reviewer. They'll stay assigned and get notified with commit & comment updates.
• Automatically: In cases where our validation checks have highest confidence the problem is legitimate and urgent. These will include a description of contextual reasoning why & actionable next steps.

File & Line	Issue
requirements.lock Line 29	The dependency update from certifi==2023.7.22 to certifi==2025.11.12 is problematic. The version number suggests a future date (2025) which is suspicious and likely indicates a typo or malicious package. This could lead to supply chain attacks if the package is compromised.
requirements-dev.lock Line 92	The dependency update from nox==2023.4.22 to nox==2025.11.12 is problematic. The version number suggests a future date (2025) which is suspicious and likely indicates a typo or malicious package. This could lead to supply chain attacks if the package is compromised.
README.md Line 133	The code change removes a hardcoded API key in the example and replaces it with a proper environment variable reference. This is a security improvement, not a vulnerability.
requirements-dev.lock Line 36	The dependency update from certifi==2023.7.22 to certifi==2025.11.12 is problematic. The version number suggests a future date (2025) which is suspicious and likely indicates a typo or malicious package. This could lead to supply chain attacks if the package is compromised.
CHANGELOG.md Line 3	This is a changelog file that only documents version history and changes. There are no security vulnerabilities introduced in the changed lines.

🧰 Analysis tools

• [ ✅ ] HackerOne AI Code Analysis
• [ ✅ ] HackerOne AI Code Validation
• [ ✅ ] semgrep
• [ ✅ ] rubocop
• [ ✅ ] bandit

⏱️ Latest scan covered changes up to commit 03828db (latest)

[pullrequest]

✅ Graham C reviewed all the included code changes and associated automation findings and determined that there were no immediately actionable security flaws. Note that they will continue to be notified of any new commits or comments and follow up as needed throughout the duration of this pull request's lifecycle.

Graham C

---

Reviewed with ❤️ by PullRequest

[pullrequest]

Graham C has submitted feedback.

Graham C

---

Reviewed with ❤️ by PullRequest

[pullrequest]

The url field accepts any string without validation, creating a potential Server-Side Request Forgery (SSRF) vulnerability. This field can contain external URLs or base64-encoded data URIs. Without validation, an attacker could provide URLs to internal services (like http://localhost:6379 or cloud metadata endpoints at http://169.254.169.254/) that the server can access but external users cannot.

According to the OWASP Input Validation Cheat Sheet, URL inputs should validate: allowed protocols (typically only https:// for external URLs), that destinations are not private IP ranges or localhost, and maximum string length. For base64 data URIs, validate the decoded size to prevent memory exhaustion.

Remediation:

Add validation in the API handler before processing URLs:

• Parse and verify scheme is https (or data for base64)
• For https URLs, block localhost, private IPs (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8)
• Enforce max length (e.g., 10KB for URLs, 10MB for data URIs)
• For data URIs, validate MIME type and decoded size

References:

• https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html
• https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html
  

🔸 Vulnerability (Warning)

Graham C

[pullrequest]

The graph_ids field accepts a list of strings without maximum length validation on either array size or individual elements. An attacker could provide an extremely large array or very long ID strings, leading to memory exhaustion and denial of service. When processing queries against specified graphs, this could also cause database performance issues.

The OWASP Input Validation Cheat Sheet states that array inputs must have maximum length validation to prevent resource exhaustion. Without bounds, attackers can force excessive memory allocation, iterate over unreasonable item counts, or construct database queries with massive IN clauses. Note that the TypedDict version in src/writerai/types/shared_params/tool_param.py has the same issue.

Remediation:

Add Pydantic field validators:

from pydantic import field_validator

@field_validator('graph_ids')
@classmethod
def validate_graph_ids(cls, v):
    if len(v) > 50:
        raise ValueError('graph_ids cannot exceed 50 items')
    for graph_id in v:
        if len(graph_id) > 256:
            raise ValueError('individual graph_id cannot exceed 256 characters')
    return v

References:

• https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html
• https://docs.pydantic.dev/latest/concepts/validators/
  

🔸 Vulnerability (Warning)

Graham C

[pullrequest]

PullRequest reviewed the updates made to #251 up until the latest commit (24004a4). No further issues were found.

Reviewed by:

Graham C