files.py

# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

from __future__ import annotations

from typing import Mapping, cast
from typing_extensions import Literal

import httpx

from ..types import file_list_params, file_create_params
from .._files import deepcopy_with_paths
from .._types import Body, Omit, Query, Headers, NotGiven, FileTypes, omit, not_given
from .._utils import extract_files, path_template, maybe_transform, async_maybe_transform
from .._compat import cached_property
from .._resource import SyncAPIResource, AsyncAPIResource
from .._response import (
    BinaryAPIResponse,
    AsyncBinaryAPIResponse,
    StreamedBinaryAPIResponse,
    AsyncStreamedBinaryAPIResponse,
    to_raw_response_wrapper,
    to_streamed_response_wrapper,
    async_to_raw_response_wrapper,
    to_custom_raw_response_wrapper,
    async_to_streamed_response_wrapper,
    to_custom_streamed_response_wrapper,
    async_to_custom_raw_response_wrapper,
    async_to_custom_streamed_response_wrapper,
)
from ..pagination import SyncPage, AsyncPage
from ..types.file import File
from .._base_client import AsyncPaginator, make_request_options

__all__ = ["FilesResource", "AsyncFilesResource"]


class FilesResource(SyncAPIResource):
    @cached_property
    def with_raw_response(self) -> FilesResourceWithRawResponse:
        """
        This property can be used as a prefix for any HTTP method call to return
        the raw response object instead of the parsed content.

        For more information, see https://www.github.com/Increase/increase-python#accessing-raw-response-data-eg-headers
        """
        return FilesResourceWithRawResponse(self)

    @cached_property
    def with_streaming_response(self) -> FilesResourceWithStreamingResponse:
        """
        An alternative to `.with_raw_response` that doesn't eagerly read the response body.

        For more information, see https://www.github.com/Increase/increase-python#with_streaming_response
        """
        return FilesResourceWithStreamingResponse(self)

    def create(
        self,
        *,
        file: FileTypes,
        purpose: Literal[
            "card_dispute_attachment",
            "check_image_front",
            "check_image_back",
            "mailed_check_image",
            "check_attachment",
            "check_voucher_image",
            "check_signature",
            "form_ss_4",
            "identity_document",
            "loan_application_supplemental_document",
            "other",
            "trust_formation_document",
            "digital_wallet_artwork",
            "digital_wallet_app_icon",
            "physical_card_front",
            "physical_card_carrier",
            "document_request",
            "entity_supplemental_document",
            "unusual_activity_report_attachment",
            "proof_of_authorization_request_submission",
        ],
        description: str | Omit = omit,
        # 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,
        idempotency_key: str | None = None,
    ) -> File:
        """
        To upload a file to Increase, you'll need to send a request of Content-Type
        `multipart/form-data`. The request should contain the file you would like to
        upload, as well as the parameters for creating a file.

        Args:
          file: The file contents. This should follow the specifications of
              [RFC 7578](https://datatracker.ietf.org/doc/html/rfc7578) which defines file
              transfers for the multipart/form-data protocol.

          purpose: What the File will be used for in Increase's systems.

              - `card_dispute_attachment` - A file to be attached to a Card Dispute.
              - `check_image_front` - An image of the front of a check, used for check
                deposits.
              - `check_image_back` - An image of the back of a check, used for check deposits.
              - `mailed_check_image` - An image of a check that was mailed to a recipient.
              - `check_attachment` - A document to be printed on an additional page and mailed
                with a check that you've requested Increase print. This must be a PDF whose
                pages are all US letter size and all have the same orientation.
              - `check_voucher_image` - An image to be used as the check voucher image, which
                is printed in the middle of the trifold area of a check. This must be a
                2550x1100 pixel PNG.
              - `check_signature` - A signature image to be printed on a check. This must be a
                1320x120 pixel PNG.
              - `form_ss_4` - IRS Form SS-4.
              - `identity_document` - An image of a government-issued ID.
              - `loan_application_supplemental_document` - A supplemental document for a Loan
                Application.
              - `other` - A file purpose not covered by any of the other cases.
              - `trust_formation_document` - A legal document forming a trust.
              - `digital_wallet_artwork` - A card image to be rendered inside digital wallet
                apps. This must be a 1536x969 pixel PNG with the Visa Brand Mark sized and
                placed as in the digital card template.
              - `digital_wallet_app_icon` - An icon for you app to be rendered inside digital
                wallet apps. This must be a 100x100 pixel PNG.
              - `physical_card_front` - A card image to be printed on the front of a physical
                card. This must be a 2100x1344 pixel PNG with a density of 600 dots per inch
                (DPI) and no other color but black.
              - `physical_card_carrier` - An image representing the entirety of the carrier
                used for a physical card. This must be a 2550x3300 pixel PNG with a density of
                300 dots per inch (DPI) and no other color but black.
              - `document_request` - A document requested by Increase.
              - `entity_supplemental_document` - A supplemental document associated an an
                Entity.
              - `unusual_activity_report_attachment` - An attachment to an Unusual Activity
                Report.
              - `proof_of_authorization_request_submission` - A file containing additional
                evidence for a Proof of Authorization Request Submission.

          description: The description you choose to give the File.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds

          idempotency_key: Specify a custom idempotency key for this request
        """
        body = deepcopy_with_paths(
            {
                "file": file,
                "purpose": purpose,
                "description": description,
            },
            [["file"]],
        )
        files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
        # It should be noted that the actual Content-Type header that will be
        # sent to the server will contain a `boundary` parameter, e.g.
        # multipart/form-data; boundary=---abc--
        extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
        return self._post(
            "/files",
            body=maybe_transform(body, file_create_params.FileCreateParams),
            files=files,
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                idempotency_key=idempotency_key,
            ),
            cast_to=File,
        )

    def retrieve(
        self,
        file_id: str,
        *,
        # 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,
    ) -> File:
        """Fetch metadata about a File, like its `purpose` and MIME type.

        To access the
        content, use the [Get File contents](/documentation/api/files#get-file-contents)
        API.

        Args:
          file_id: The identifier of the File.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not file_id:
            raise ValueError(f"Expected a non-empty value for `file_id` but received {file_id!r}")
        return self._get(
            path_template("/files/{file_id}", file_id=file_id),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=File,
        )

    def list(
        self,
        *,
        created_at: file_list_params.CreatedAt | Omit = omit,
        cursor: str | Omit = omit,
        idempotency_key: str | Omit = omit,
        limit: int | Omit = omit,
        purpose: file_list_params.Purpose | Omit = omit,
        # 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,
    ) -> SyncPage[File]:
        """
        List Files

        Args:
          cursor: Return the page of entries after this one.

          idempotency_key: Filter records to the one with the specified `idempotency_key` you chose for
              that object. This value is unique across Increase and is used to ensure that a
              request is only processed once. Learn more about
              [idempotency](https://increase.com/documentation/idempotency-keys).

          limit: Limit the size of the list that is returned. The default (and maximum) is 100
              objects.

              Defaults to `100`.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        return self._get_api_list(
            "/files",
            page=SyncPage[File],
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                query=maybe_transform(
                    {
                        "created_at": created_at,
                        "cursor": cursor,
                        "idempotency_key": idempotency_key,
                        "limit": limit,
                        "purpose": purpose,
                    },
                    file_list_params.FileListParams,
                ),
            ),
            model=File,
        )

    def contents(
        self,
        file_id: str,
        *,
        # 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,
    ) -> BinaryAPIResponse:
        """Download the contents of a File.

        Responds with a 307 redirect whose `Location`
        header points at a short-lived, pre-signed URL. Our
        [SDKs](/documentation/software-development-kits) follow the redirect and return
        the File's contents; if you call the API directly, follow the redirect to
        download it. The pre-signed URL serves the File with a `Content-Type` matching
        its `mime` and a `Content-Disposition` header set to its `filename`. It expires
        in 10 minutes. To share a File with someone who doesn't have access to your API
        key, create a File Link.

        Args:
          file_id: The identifier of the File.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not file_id:
            raise ValueError(f"Expected a non-empty value for `file_id` but received {file_id!r}")
        extra_headers = {"Accept": "application/octet-stream", **(extra_headers or {})}
        return self._get(
            path_template("/files/{file_id}/contents", file_id=file_id),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=BinaryAPIResponse,
        )


class AsyncFilesResource(AsyncAPIResource):
    @cached_property
    def with_raw_response(self) -> AsyncFilesResourceWithRawResponse:
        """
        This property can be used as a prefix for any HTTP method call to return
        the raw response object instead of the parsed content.

        For more information, see https://www.github.com/Increase/increase-python#accessing-raw-response-data-eg-headers
        """
        return AsyncFilesResourceWithRawResponse(self)

    @cached_property
    def with_streaming_response(self) -> AsyncFilesResourceWithStreamingResponse:
        """
        An alternative to `.with_raw_response` that doesn't eagerly read the response body.

        For more information, see https://www.github.com/Increase/increase-python#with_streaming_response
        """
        return AsyncFilesResourceWithStreamingResponse(self)

    async def create(
        self,
        *,
        file: FileTypes,
        purpose: Literal[
            "card_dispute_attachment",
            "check_image_front",
            "check_image_back",
            "mailed_check_image",
            "check_attachment",
            "check_voucher_image",
            "check_signature",
            "form_ss_4",
            "identity_document",
            "loan_application_supplemental_document",
            "other",
            "trust_formation_document",
            "digital_wallet_artwork",
            "digital_wallet_app_icon",
            "physical_card_front",
            "physical_card_carrier",
            "document_request",
            "entity_supplemental_document",
            "unusual_activity_report_attachment",
            "proof_of_authorization_request_submission",
        ],
        description: str | Omit = omit,
        # 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,
        idempotency_key: str | None = None,
    ) -> File:
        """
        To upload a file to Increase, you'll need to send a request of Content-Type
        `multipart/form-data`. The request should contain the file you would like to
        upload, as well as the parameters for creating a file.

        Args:
          file: The file contents. This should follow the specifications of
              [RFC 7578](https://datatracker.ietf.org/doc/html/rfc7578) which defines file
              transfers for the multipart/form-data protocol.

          purpose: What the File will be used for in Increase's systems.

              - `card_dispute_attachment` - A file to be attached to a Card Dispute.
              - `check_image_front` - An image of the front of a check, used for check
                deposits.
              - `check_image_back` - An image of the back of a check, used for check deposits.
              - `mailed_check_image` - An image of a check that was mailed to a recipient.
              - `check_attachment` - A document to be printed on an additional page and mailed
                with a check that you've requested Increase print. This must be a PDF whose
                pages are all US letter size and all have the same orientation.
              - `check_voucher_image` - An image to be used as the check voucher image, which
                is printed in the middle of the trifold area of a check. This must be a
                2550x1100 pixel PNG.
              - `check_signature` - A signature image to be printed on a check. This must be a
                1320x120 pixel PNG.
              - `form_ss_4` - IRS Form SS-4.
              - `identity_document` - An image of a government-issued ID.
              - `loan_application_supplemental_document` - A supplemental document for a Loan
                Application.
              - `other` - A file purpose not covered by any of the other cases.
              - `trust_formation_document` - A legal document forming a trust.
              - `digital_wallet_artwork` - A card image to be rendered inside digital wallet
                apps. This must be a 1536x969 pixel PNG with the Visa Brand Mark sized and
                placed as in the digital card template.
              - `digital_wallet_app_icon` - An icon for you app to be rendered inside digital
                wallet apps. This must be a 100x100 pixel PNG.
              - `physical_card_front` - A card image to be printed on the front of a physical
                card. This must be a 2100x1344 pixel PNG with a density of 600 dots per inch
                (DPI) and no other color but black.
              - `physical_card_carrier` - An image representing the entirety of the carrier
                used for a physical card. This must be a 2550x3300 pixel PNG with a density of
                300 dots per inch (DPI) and no other color but black.
              - `document_request` - A document requested by Increase.
              - `entity_supplemental_document` - A supplemental document associated an an
                Entity.
              - `unusual_activity_report_attachment` - An attachment to an Unusual Activity
                Report.
              - `proof_of_authorization_request_submission` - A file containing additional
                evidence for a Proof of Authorization Request Submission.

          description: The description you choose to give the File.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds

          idempotency_key: Specify a custom idempotency key for this request
        """
        body = deepcopy_with_paths(
            {
                "file": file,
                "purpose": purpose,
                "description": description,
            },
            [["file"]],
        )
        files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
        # It should be noted that the actual Content-Type header that will be
        # sent to the server will contain a `boundary` parameter, e.g.
        # multipart/form-data; boundary=---abc--
        extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
        return await self._post(
            "/files",
            body=await async_maybe_transform(body, file_create_params.FileCreateParams),
            files=files,
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                idempotency_key=idempotency_key,
            ),
            cast_to=File,
        )

    async def retrieve(
        self,
        file_id: str,
        *,
        # 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,
    ) -> File:
        """Fetch metadata about a File, like its `purpose` and MIME type.

        To access the
        content, use the [Get File contents](/documentation/api/files#get-file-contents)
        API.

        Args:
          file_id: The identifier of the File.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not file_id:
            raise ValueError(f"Expected a non-empty value for `file_id` but received {file_id!r}")
        return await self._get(
            path_template("/files/{file_id}", file_id=file_id),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=File,
        )

    def list(
        self,
        *,
        created_at: file_list_params.CreatedAt | Omit = omit,
        cursor: str | Omit = omit,
        idempotency_key: str | Omit = omit,
        limit: int | Omit = omit,
        purpose: file_list_params.Purpose | Omit = omit,
        # 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,
    ) -> AsyncPaginator[File, AsyncPage[File]]:
        """
        List Files

        Args:
          cursor: Return the page of entries after this one.

          idempotency_key: Filter records to the one with the specified `idempotency_key` you chose for
              that object. This value is unique across Increase and is used to ensure that a
              request is only processed once. Learn more about
              [idempotency](https://increase.com/documentation/idempotency-keys).

          limit: Limit the size of the list that is returned. The default (and maximum) is 100
              objects.

              Defaults to `100`.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        return self._get_api_list(
            "/files",
            page=AsyncPage[File],
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                query=maybe_transform(
                    {
                        "created_at": created_at,
                        "cursor": cursor,
                        "idempotency_key": idempotency_key,
                        "limit": limit,
                        "purpose": purpose,
                    },
                    file_list_params.FileListParams,
                ),
            ),
            model=File,
        )

    async def contents(
        self,
        file_id: str,
        *,
        # 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,
    ) -> AsyncBinaryAPIResponse:
        """Download the contents of a File.

        Responds with a 307 redirect whose `Location`
        header points at a short-lived, pre-signed URL. Our
        [SDKs](/documentation/software-development-kits) follow the redirect and return
        the File's contents; if you call the API directly, follow the redirect to
        download it. The pre-signed URL serves the File with a `Content-Type` matching
        its `mime` and a `Content-Disposition` header set to its `filename`. It expires
        in 10 minutes. To share a File with someone who doesn't have access to your API
        key, create a File Link.

        Args:
          file_id: The identifier of the File.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not file_id:
            raise ValueError(f"Expected a non-empty value for `file_id` but received {file_id!r}")
        extra_headers = {"Accept": "application/octet-stream", **(extra_headers or {})}
        return await self._get(
            path_template("/files/{file_id}/contents", file_id=file_id),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=AsyncBinaryAPIResponse,
        )


class FilesResourceWithRawResponse:
    def __init__(self, files: FilesResource) -> None:
        self._files = files

        self.create = to_raw_response_wrapper(
            files.create,
        )
        self.retrieve = to_raw_response_wrapper(
            files.retrieve,
        )
        self.list = to_raw_response_wrapper(
            files.list,
        )
        self.contents = to_custom_raw_response_wrapper(
            files.contents,
            BinaryAPIResponse,
        )


class AsyncFilesResourceWithRawResponse:
    def __init__(self, files: AsyncFilesResource) -> None:
        self._files = files

        self.create = async_to_raw_response_wrapper(
            files.create,
        )
        self.retrieve = async_to_raw_response_wrapper(
            files.retrieve,
        )
        self.list = async_to_raw_response_wrapper(
            files.list,
        )
        self.contents = async_to_custom_raw_response_wrapper(
            files.contents,
            AsyncBinaryAPIResponse,
        )


class FilesResourceWithStreamingResponse:
    def __init__(self, files: FilesResource) -> None:
        self._files = files

        self.create = to_streamed_response_wrapper(
            files.create,
        )
        self.retrieve = to_streamed_response_wrapper(
            files.retrieve,
        )
        self.list = to_streamed_response_wrapper(
            files.list,
        )
        self.contents = to_custom_streamed_response_wrapper(
            files.contents,
            StreamedBinaryAPIResponse,
        )


class AsyncFilesResourceWithStreamingResponse:
    def __init__(self, files: AsyncFilesResource) -> None:
        self._files = files

        self.create = async_to_streamed_response_wrapper(
            files.create,
        )
        self.retrieve = async_to_streamed_response_wrapper(
            files.retrieve,
        )
        self.list = async_to_streamed_response_wrapper(
            files.list,
        )
        self.contents = async_to_custom_streamed_response_wrapper(
            files.contents,
            AsyncStreamedBinaryAPIResponse,
        )