docs(api): updates to API spec (#170)

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 27
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-95e5c41bc4917566fc6ee1f849795bac2e34e5609afd25bb927252ac7e33e2f0.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-ffd1e266059dd5eabc5a0a437bbf4c7b06d497152e076a91e0cc25243a485344.yml

api.md

@@ -47,7 +47,7 @@ Methods:
 
 - <code title="post /v1/applications/{application_id}/jobs">client.applications.jobs.<a href="./src/writerai/resources/applications/jobs.py">create</a>(application_id, \*\*<a href="src/writerai/types/applications/job_create_params.py">params</a>) -> <a href="./src/writerai/types/applications/job_create_response.py">JobCreateResponse</a></code>
 - <code title="get /v1/applications/jobs/{job_id}">client.applications.jobs.<a href="./src/writerai/resources/applications/jobs.py">retrieve</a>(job_id) -> <a href="./src/writerai/types/applications/job_retrieve_response.py">JobRetrieveResponse</a></code>
-- <code title="get /v1/applications/{application_id}/jobs">client.applications.jobs.<a href="./src/writerai/resources/applications/jobs.py">list</a>(application_id, \*\*<a href="src/writerai/types/applications/job_list_params.py">params</a>) -> <a href="./src/writerai/types/applications/job_list_response.py">JobListResponse</a></code>
+- <code title="get /v1/applications/{application_id}/jobs">client.applications.jobs.<a href="./src/writerai/resources/applications/jobs.py">list</a>(application_id, \*\*<a href="src/writerai/types/applications/job_list_params.py">params</a>) -> <a href="./src/writerai/types/applications/job_list_response.py">SyncApplicationJobsOffset[JobListResponse]</a></code>
 - <code title="post /v1/applications/jobs/{job_id}/retry">client.applications.jobs.<a href="./src/writerai/resources/applications/jobs.py">retry</a>(job_id) -> <a href="./src/writerai/types/applications/job_retry_response.py">JobRetryResponse</a></code>
 
 ## Graphs

src/writerai/resources/applications/graphs.py

@@ -59,10 +59,13 @@ def update(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> ApplicationGraphsResponse:
         """
-        Associate graphs with a no-code chat application via API.
+        Updates the graphs listed and associates them with the no-code chat app to be
+        used.
 
         Args:
-          graph_ids: A list of graph IDs to associate with the application.
+          graph_ids: A list of graph IDs to associate with the application. Note that this will
+              replace the existing list of graphs associated with the application, not add to
+              it.
 
           extra_headers: Send extra headers
 
@@ -150,10 +153,13 @@ async def update(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> ApplicationGraphsResponse:
         """
-        Associate graphs with a no-code chat application via API.
+        Updates the graphs listed and associates them with the no-code chat app to be
+        used.
 
         Args:
-          graph_ids: A list of graph IDs to associate with the application.
+          graph_ids: A list of graph IDs to associate with the application. Note that this will
+              replace the existing list of graphs associated with the application, not add to
+              it.
 
           extra_headers: Send extra headers
 

src/writerai/resources/applications/jobs.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from typing import Dict, Iterable
+from typing import Iterable
+from typing_extensions import Literal
 
 import httpx
 
@@ -19,7 +20,8 @@
     async_to_raw_response_wrapper,
     async_to_streamed_response_wrapper,
 )
-from ..._base_client import make_request_options
+from ...pagination import SyncApplicationJobsOffset, AsyncApplicationJobsOffset
+from ..._base_client import AsyncPaginator, make_request_options
 from ...types.applications import job_list_params, job_create_params
 from ...types.applications.job_list_response import JobListResponse
 from ...types.applications.job_retry_response import JobRetryResponse
@@ -54,7 +56,6 @@ def create(
         application_id: str,
         *,
         inputs: Iterable[job_create_params.Input],
-        metadata: Dict[str, str] | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -68,8 +69,6 @@ def create(
         Args:
           inputs: A list of input objects to generate content for.
 
-          metadata: Optional metadata for the generation request.
-
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -82,13 +81,7 @@ def create(
             raise ValueError(f"Expected a non-empty value for `application_id` but received {application_id!r}")
         return self._post(
             f"/v1/applications/{application_id}/jobs",
-            body=maybe_transform(
-                {
-                    "inputs": inputs,
-                    "metadata": metadata,
-                },
-                job_create_params.JobCreateParams,
-            ),
+            body=maybe_transform({"inputs": inputs}, job_create_params.JobCreateParams),
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
@@ -134,19 +127,25 @@ def list(
         *,
         limit: int | NotGiven = NOT_GIVEN,
         offset: int | NotGiven = NOT_GIVEN,
-        status: job_list_params.Status | NotGiven = NOT_GIVEN,
+        status: Literal["in_progress", "failed", "completed"] | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
-    ) -> JobListResponse:
+    ) -> SyncApplicationJobsOffset[JobListResponse]:
         """
         Retrieve all jobs created via the async API, linked to the provided application
         ID (or alias).
 
         Args:
+          limit: The pagination limit for retrieving the jobs.
+
+          offset: The pagination offset for retrieving the jobs.
+
+          status: The status of the job.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -157,8 +156,9 @@ def list(
         """
         if not application_id:
             raise ValueError(f"Expected a non-empty value for `application_id` but received {application_id!r}")
-        return self._get(
+        return self._get_api_list(
             f"/v1/applications/{application_id}/jobs",
+            page=SyncApplicationJobsOffset[JobListResponse],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -173,7 +173,7 @@ def list(
                     job_list_params.JobListParams,
                 ),
             ),
-            cast_to=JobListResponse,
+            model=JobListResponse,
         )
 
     def retry(
@@ -236,7 +236,6 @@ async def create(
         application_id: str,
         *,
         inputs: Iterable[job_create_params.Input],
-        metadata: Dict[str, str] | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -250,8 +249,6 @@ async def create(
         Args:
           inputs: A list of input objects to generate content for.
 
-          metadata: Optional metadata for the generation request.
-
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -264,13 +261,7 @@ async def create(
             raise ValueError(f"Expected a non-empty value for `application_id` but received {application_id!r}")
         return await self._post(
             f"/v1/applications/{application_id}/jobs",
-            body=await async_maybe_transform(
-                {
-                    "inputs": inputs,
-                    "metadata": metadata,
-                },
-                job_create_params.JobCreateParams,
-            ),
+            body=await async_maybe_transform({"inputs": inputs}, job_create_params.JobCreateParams),
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
@@ -310,25 +301,31 @@ async def retrieve(
             cast_to=JobRetrieveResponse,
         )
 
-    async def list(
+    def list(
         self,
         application_id: str,
         *,
         limit: int | NotGiven = NOT_GIVEN,
         offset: int | NotGiven = NOT_GIVEN,
-        status: job_list_params.Status | NotGiven = NOT_GIVEN,
+        status: Literal["in_progress", "failed", "completed"] | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
-    ) -> JobListResponse:
+    ) -> AsyncPaginator[JobListResponse, AsyncApplicationJobsOffset[JobListResponse]]:
         """
         Retrieve all jobs created via the async API, linked to the provided application
         ID (or alias).
 
         Args:
+          limit: The pagination limit for retrieving the jobs.
+
+          offset: The pagination offset for retrieving the jobs.
+
+          status: The status of the job.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -339,14 +336,15 @@ async def list(
         """
         if not application_id:
             raise ValueError(f"Expected a non-empty value for `application_id` but received {application_id!r}")
-        return await self._get(
+        return self._get_api_list(
             f"/v1/applications/{application_id}/jobs",
+            page=AsyncApplicationJobsOffset[JobListResponse],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
                 extra_body=extra_body,
                 timeout=timeout,
-                query=await async_maybe_transform(
+                query=maybe_transform(
                     {
                         "limit": limit,
                         "offset": offset,
@@ -355,7 +353,7 @@ async def list(
                     job_list_params.JobListParams,
                 ),
             ),
-            cast_to=JobListResponse,
+            model=JobListResponse,
         )
 
     async def retry(

src/writerai/types/applications/graph_update_params.py

@@ -10,4 +10,8 @@
 
 class GraphUpdateParams(TypedDict, total=False):
     graph_ids: Required[List[str]]
-    """A list of graph IDs to associate with the application."""
+    """A list of graph IDs to associate with the application.
+
+    Note that this will replace the existing list of graphs associated with the
+    application, not add to it.
+    """

src/writerai/types/applications/job_create_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict, Iterable
+from typing import List, Iterable
 from typing_extensions import Required, TypedDict
 
 __all__ = ["JobCreateParams", "Input"]
@@ -12,13 +12,20 @@ class JobCreateParams(TypedDict, total=False):
     inputs: Required[Iterable[Input]]
     """A list of input objects to generate content for."""
 
-    metadata: Dict[str, str]
-    """Optional metadata for the generation request."""
-
 
 class Input(TypedDict, total=False):
-    content: str
-    """The input content to be processed."""
+    id: Required[str]
+    """The unique identifier for the input field from the application.
+
+    All input types from the No-code application are supported (i.e. Text input,
+    Dropdown, File upload, Image input). The identifier should be the name of the
+    input type.
+    """
+
+    value: Required[List[str]]
+    """The value for the input field.
 
-    input_id: str
-    """A unique identifier for the input object."""
+    If file is required you will need to pass a `file_id`. See
+    [here](https://dev.writer.com/api-guides/api-reference/file-api/upload-files)
+    for the Files API.
+    """

src/writerai/types/applications/job_create_response.py

@@ -1,22 +1,19 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Optional
 from datetime import datetime
+from typing_extensions import Literal
 
 from ..._models import BaseModel
 
 __all__ = ["JobCreateResponse"]
 
 
 class JobCreateResponse(BaseModel):
-    job_id: str
+    id: str
     """The unique identifier for the async job created."""
 
-    application_id: Optional[str] = None
-    """The ID of the application associated with this job."""
-
-    created_at: Optional[datetime] = None
+    created_at: datetime
     """The timestamp when the job was created."""
 
-    status: Optional[str] = None
-    """The initial status of the job (e.g., 'queued')."""
+    status: Literal["in_progress", "failed", "completed"]
+    """The status of the job."""

src/writerai/types/applications/job_list_params.py

@@ -2,40 +2,17 @@
 
 from __future__ import annotations
 
-from typing import Union, Iterable
-from datetime import datetime
-from typing_extensions import Required, Annotated, TypedDict
+from typing_extensions import Literal, TypedDict
 
-from ..._utils import PropertyInfo
-
-__all__ = ["JobListParams", "Status", "StatusJob"]
+__all__ = ["JobListParams"]
 
 
 class JobListParams(TypedDict, total=False):
     limit: int
+    """The pagination limit for retrieving the jobs."""
 
     offset: int
+    """The pagination offset for retrieving the jobs."""
 
-    status: Status
-
-
-class StatusJob(TypedDict, total=False):
-    created_at: Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]
-    """The timestamp when the job was created."""
-
-    job_id: str
-    """The unique identifier for the job."""
-
-    result: str
-    """The result of the completed job, if applicable."""
-
-    status: str
-    """The current status of the job."""
-
-    updated_at: Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]
-    """The timestamp when the job was last updated."""
-
-
-class Status(TypedDict, total=False):
-    jobs: Required[Iterable[StatusJob]]
-    """A list of jobs associated with the application."""
+    status: Literal["in_progress", "failed", "completed"]
+    """The status of the job."""