client.py

# This file was auto-generated by Fern from our API Definition.

from __future__ import annotations

import typing

from .. import core
from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.documents_commit_response import DocumentsCommitResponse
from ..types.documents_get_response import DocumentsGetResponse
from ..types.documents_import_from200response import DocumentsImportFrom200Response
from ..types.documents_init_response import DocumentsInitResponse
from ..types.documents_list_response import DocumentsListResponse
from ..types.documents_update_response import DocumentsUpdateResponse
from ..types.documents_upload_proxy_response import DocumentsUploadProxyResponse
from .raw_client import AsyncRawDocumentsClient, RawDocumentsClient
from .types.documents_import_from_request_dedup_mode import DocumentsImportFromRequestDedupMode
from .types.documents_import_from_request_expected import DocumentsImportFromRequestExpected
from .types.documents_import_from_request_mode import DocumentsImportFromRequestMode
from .types.documents_import_from_request_source import DocumentsImportFromRequestSource
from .types.documents_init_request_dedup_mode import DocumentsInitRequestDedupMode
from .types.documents_init_request_upload_preference import DocumentsInitRequestUploadPreference
from .types.list_documents_request_order import ListDocumentsRequestOrder
from .types.list_documents_request_sort import ListDocumentsRequestSort
from .types.list_documents_request_state import ListDocumentsRequestState

if typing.TYPE_CHECKING:
    from .layers.client import AsyncLayersClient, LayersClient
# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class DocumentsClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawDocumentsClient(client_wrapper=client_wrapper)
        self._client_wrapper = client_wrapper
        self._layers: typing.Optional[LayersClient] = None

    @property
    def with_raw_response(self) -> RawDocumentsClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawDocumentsClient
        """
        return self._raw_client

    def list(
        self,
        tenant_id: str,
        *,
        limit: typing.Optional[int] = None,
        cursor: typing.Optional[str] = None,
        state: typing.Optional[ListDocumentsRequestState] = None,
        q: typing.Optional[str] = None,
        folder_id: typing.Optional[str] = None,
        sort: typing.Optional[ListDocumentsRequestSort] = None,
        order: typing.Optional[ListDocumentsRequestOrder] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> DocumentsListResponse:
        """
        Parameters
        ----------
        tenant_id : str

        limit : typing.Optional[int]

        cursor : typing.Optional[str]

        state : typing.Optional[ListDocumentsRequestState]
            Only documents in this state. Without it, every state except deleting.

        q : typing.Optional[str]
            Only documents whose name contains this text, ignoring case.

        folder_id : typing.Optional[str]
            Only documents directly in this folder (root: the top level). Without it, documents in every folder.

        sort : typing.Optional[ListDocumentsRequestSort]
            createdAt (default), name (ignoring case), or size (stored bytes; 0 while pending).

        order : typing.Optional[ListDocumentsRequestOrder]
            Defaults to the reading order of the sort: A to Z for name, newest and largest first otherwise.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsListResponse
            OK

        Examples
        --------
        from cloudpdf import CloudPDFClient

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.list(
            tenant_id="tenantId",
        )
        """
        _response = self._raw_client.list(
            tenant_id,
            limit=limit,
            cursor=cursor,
            state=state,
            q=q,
            folder_id=folder_id,
            sort=sort,
            order=order,
            request_options=request_options,
        )
        return _response.data

    def get(
        self, tenant_id: str, doc_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> DocumentsGetResponse:
        """
        Parameters
        ----------
        tenant_id : str

        doc_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsGetResponse
            OK

        Examples
        --------
        from cloudpdf import CloudPDFClient

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.get(
            tenant_id="tenantId",
            doc_id="docId",
        )
        """
        _response = self._raw_client.get(tenant_id, doc_id, request_options=request_options)
        return _response.data

    def delete(self, tenant_id: str, doc_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
        """
        Parameters
        ----------
        tenant_id : str

        doc_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        from cloudpdf import CloudPDFClient

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.delete(
            tenant_id="tenantId",
            doc_id="docId",
        )
        """
        _response = self._raw_client.delete(tenant_id, doc_id, request_options=request_options)
        return _response.data

    def update(
        self, tenant_id: str, doc_id: str, *, name: str, request_options: typing.Optional[RequestOptions] = None
    ) -> DocumentsUpdateResponse:
        """
        A document that is being deleted answers 404.

        Parameters
        ----------
        tenant_id : str

        doc_id : str

        name : str
            What people call the document: shown in dashboards, searched and sorted by. 1 to 255 characters, no control characters, no leading or trailing whitespace. Names need not be unique.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsUpdateResponse
            OK

        Examples
        --------
        from cloudpdf import CloudPDFClient

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.update(
            tenant_id="tenantId",
            doc_id="docId",
            name="name",
        )
        """
        _response = self._raw_client.update(tenant_id, doc_id, name=name, request_options=request_options)
        return _response.data

    def commit(
        self, tenant_id: str, doc_id: str, *, sha256: str, request_options: typing.Optional[RequestOptions] = None
    ) -> DocumentsCommitResponse:
        """
        An upload token commits only the documents it started; any other document answers 404.

        Parameters
        ----------
        tenant_id : str

        doc_id : str

        sha256 : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsCommitResponse
            OK

        Examples
        --------
        from cloudpdf import CloudPDFClient

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.commit(
            tenant_id="tenantId",
            doc_id="docId",
            sha256="sha256",
        )
        """
        _response = self._raw_client.commit(tenant_id, doc_id, sha256=sha256, request_options=request_options)
        return _response.data

    def download(
        self, tenant_id: str, doc_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Iterator[bytes]:
        """
        Parameters
        ----------
        tenant_id : str

        doc_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration. You can pass in configuration such as `chunk_size`, and more to customize the request and response.

        Returns
        -------
        typing.Iterator[bytes]
            OK

        Examples
        --------
        from cloudpdf import CloudPDFClient

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.download(
            tenant_id="tenantId",
            doc_id="docId",
        )
        """
        with self._raw_client.download(tenant_id, doc_id, request_options=request_options) as r:
            yield from r.data

    def thumbnail(
        self, tenant_id: str, doc_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Iterator[bytes]:
        """
        Parameters
        ----------
        tenant_id : str

        doc_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration. You can pass in configuration such as `chunk_size`, and more to customize the request and response.

        Returns
        -------
        typing.Iterator[bytes]
            OK

        Examples
        --------
        from cloudpdf import CloudPDFClient

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.thumbnail(
            tenant_id="tenantId",
            doc_id="docId",
        )
        """
        with self._raw_client.thumbnail(tenant_id, doc_id, request_options=request_options) as r:
            yield from r.data

    def upload_proxy(
        self, tenant_id: str, doc_id: str, *, file: core.File, request_options: typing.Optional[RequestOptions] = None
    ) -> DocumentsUploadProxyResponse:
        """
        This bounded origin-mediated fallback must only be used after documents.init returns upload.kind=proxy. Auto mode prefers a presigned object-store PUT whenever available. An upload token sends files only to the documents it started.

        Parameters
        ----------
        tenant_id : str

        doc_id : str

        file : core.File
            See core.File for more documentation

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsUploadProxyResponse
            OK

        Examples
        --------
        from cloudpdf import CloudPDFClient

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.upload_proxy(
            tenant_id="tenantId",
            doc_id="docId",
        )
        """
        _response = self._raw_client.upload_proxy(tenant_id, doc_id, file=file, request_options=request_options)
        return _response.data

    def import_from(
        self,
        tenant_id: str,
        *,
        source: DocumentsImportFromRequestSource,
        expected: typing.Optional[DocumentsImportFromRequestExpected] = OMIT,
        name: typing.Optional[str] = OMIT,
        folder_id: typing.Optional[str] = OMIT,
        metadata: typing.Optional[typing.Dict[str, typing.Any]] = OMIT,
        idempotency_key: typing.Optional[str] = OMIT,
        dedup_mode: typing.Optional[DocumentsImportFromRequestDedupMode] = OMIT,
        doc_id: typing.Optional[str] = OMIT,
        mode: typing.Optional[DocumentsImportFromRequestMode] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> DocumentsImportFrom200Response:
        """
        Default mode is synchronous and bounded: the response returns only after the transfer verified and committed (or failed). mode=async (connection sources only) answers 202 immediately and an in-process worker performs the transfer with leased, fenced retries; poll the document until ready/failed. The deployment import policy gates scheme, network range, and size; sources must declare a length. CloudPDF copies and owns the bytes — the source is never referenced in place. A 502 marks a retryable upstream failure: retry with the same idempotencyKey to resume the same document. URL sources are capabilities and never echoed back. Connection sources name operator-registered storage (bucket/prefix scope, allowed credential classes, and tenant bindings are deployment configuration); `revision` is provider-interpreted (S3 VersionId, GCS generation, Azure version id).

        Parameters
        ----------
        tenant_id : str

        source : DocumentsImportFromRequestSource
            Where CloudPDF pulls the bytes from. The two shapes differ in who supplies the authority to read, not in which storage vendor holds the file.

        expected : typing.Optional[DocumentsImportFromRequestExpected]
            Integrity pins, enforced when present. When absent, the server-observed values become authoritative.

        name : typing.Optional[str]
            What people call the document: shown in dashboards, searched and sorted by. 1 to 255 characters, no control characters, no leading or trailing whitespace. Names need not be unique.

        folder_id : typing.Optional[str]
            A folder id, or root for the top level.

        metadata : typing.Optional[typing.Dict[str, typing.Any]]

        idempotency_key : typing.Optional[str]
            Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.

        dedup_mode : typing.Optional[DocumentsImportFromRequestDedupMode]
            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.

        doc_id : typing.Optional[str]

        mode : typing.Optional[DocumentsImportFromRequestMode]
            sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsImportFrom200Response
            OK

        Examples
        --------
        from cloudpdf import CloudPDFClient
        from cloudpdf.documents import DocumentsImportFromRequestSource_Url

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.import_from(
            tenant_id="tenantId",
            source=DocumentsImportFromRequestSource_Url(
                url="url",
            ),
        )
        """
        _response = self._raw_client.import_from(
            tenant_id,
            source=source,
            expected=expected,
            name=name,
            folder_id=folder_id,
            metadata=metadata,
            idempotency_key=idempotency_key,
            dedup_mode=dedup_mode,
            doc_id=doc_id,
            mode=mode,
            request_options=request_options,
        )
        return _response.data

    def init(
        self,
        tenant_id: str,
        *,
        size_bytes: int,
        content_sha256: str,
        name: typing.Optional[str] = OMIT,
        folder_id: typing.Optional[str] = OMIT,
        metadata: typing.Optional[typing.Dict[str, typing.Any]] = OMIT,
        idempotency_key: typing.Optional[str] = OMIT,
        dedup_mode: typing.Optional[DocumentsInitRequestDedupMode] = OMIT,
        doc_id: typing.Optional[str] = OMIT,
        upload_ttl_seconds: typing.Optional[int] = OMIT,
        upload_preference: typing.Optional[DocumentsInitRequestUploadPreference] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> DocumentsInitResponse:
        """
        With an upload token, the document goes into the token's folder with the token's metadata, whatever the request says; sizeBytes must be within the token's maxBytes, and the token makes at most maxFiles documents (403 after). docId, idempotencyKey and dedupMode reuse-existing are refused (400): each could reach a document the token didn't make.

        Parameters
        ----------
        tenant_id : str

        size_bytes : int

        content_sha256 : str

        name : typing.Optional[str]
            What people call the document: shown in dashboards, searched and sorted by. 1 to 255 characters, no control characters, no leading or trailing whitespace. Names need not be unique.

        folder_id : typing.Optional[str]
            A folder id, or root for the top level.

        metadata : typing.Optional[typing.Dict[str, typing.Any]]

        idempotency_key : typing.Optional[str]

        dedup_mode : typing.Optional[DocumentsInitRequestDedupMode]
            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.

        doc_id : typing.Optional[str]

        upload_ttl_seconds : typing.Optional[int]

        upload_preference : typing.Optional[DocumentsInitRequestUploadPreference]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsInitResponse
            OK

        Examples
        --------
        from cloudpdf import CloudPDFClient

        client = CloudPDFClient(
            token="YOUR_TOKEN",
        )
        client.documents.init(
            tenant_id="tenantId",
            size_bytes=1,
            content_sha256="contentSha256",
        )
        """
        _response = self._raw_client.init(
            tenant_id,
            size_bytes=size_bytes,
            content_sha256=content_sha256,
            name=name,
            folder_id=folder_id,
            metadata=metadata,
            idempotency_key=idempotency_key,
            dedup_mode=dedup_mode,
            doc_id=doc_id,
            upload_ttl_seconds=upload_ttl_seconds,
            upload_preference=upload_preference,
            request_options=request_options,
        )
        return _response.data

    @property
    def layers(self):
        if self._layers is None:
            from .layers.client import LayersClient  # noqa: E402

            self._layers = LayersClient(client_wrapper=self._client_wrapper)
        return self._layers


class AsyncDocumentsClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawDocumentsClient(client_wrapper=client_wrapper)
        self._client_wrapper = client_wrapper
        self._layers: typing.Optional[AsyncLayersClient] = None

    @property
    def with_raw_response(self) -> AsyncRawDocumentsClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawDocumentsClient
        """
        return self._raw_client

    async def list(
        self,
        tenant_id: str,
        *,
        limit: typing.Optional[int] = None,
        cursor: typing.Optional[str] = None,
        state: typing.Optional[ListDocumentsRequestState] = None,
        q: typing.Optional[str] = None,
        folder_id: typing.Optional[str] = None,
        sort: typing.Optional[ListDocumentsRequestSort] = None,
        order: typing.Optional[ListDocumentsRequestOrder] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> DocumentsListResponse:
        """
        Parameters
        ----------
        tenant_id : str

        limit : typing.Optional[int]

        cursor : typing.Optional[str]

        state : typing.Optional[ListDocumentsRequestState]
            Only documents in this state. Without it, every state except deleting.

        q : typing.Optional[str]
            Only documents whose name contains this text, ignoring case.

        folder_id : typing.Optional[str]
            Only documents directly in this folder (root: the top level). Without it, documents in every folder.

        sort : typing.Optional[ListDocumentsRequestSort]
            createdAt (default), name (ignoring case), or size (stored bytes; 0 while pending).

        order : typing.Optional[ListDocumentsRequestOrder]
            Defaults to the reading order of the sort: A to Z for name, newest and largest first otherwise.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsListResponse
            OK

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.list(
                tenant_id="tenantId",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.list(
            tenant_id,
            limit=limit,
            cursor=cursor,
            state=state,
            q=q,
            folder_id=folder_id,
            sort=sort,
            order=order,
            request_options=request_options,
        )
        return _response.data

    async def get(
        self, tenant_id: str, doc_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> DocumentsGetResponse:
        """
        Parameters
        ----------
        tenant_id : str

        doc_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsGetResponse
            OK

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.get(
                tenant_id="tenantId",
                doc_id="docId",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get(tenant_id, doc_id, request_options=request_options)
        return _response.data

    async def delete(
        self, tenant_id: str, doc_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> None:
        """
        Parameters
        ----------
        tenant_id : str

        doc_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.delete(
                tenant_id="tenantId",
                doc_id="docId",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.delete(tenant_id, doc_id, request_options=request_options)
        return _response.data

    async def update(
        self, tenant_id: str, doc_id: str, *, name: str, request_options: typing.Optional[RequestOptions] = None
    ) -> DocumentsUpdateResponse:
        """
        A document that is being deleted answers 404.

        Parameters
        ----------
        tenant_id : str

        doc_id : str

        name : str
            What people call the document: shown in dashboards, searched and sorted by. 1 to 255 characters, no control characters, no leading or trailing whitespace. Names need not be unique.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsUpdateResponse
            OK

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.update(
                tenant_id="tenantId",
                doc_id="docId",
                name="name",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.update(tenant_id, doc_id, name=name, request_options=request_options)
        return _response.data

    async def commit(
        self, tenant_id: str, doc_id: str, *, sha256: str, request_options: typing.Optional[RequestOptions] = None
    ) -> DocumentsCommitResponse:
        """
        An upload token commits only the documents it started; any other document answers 404.

        Parameters
        ----------
        tenant_id : str

        doc_id : str

        sha256 : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsCommitResponse
            OK

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.commit(
                tenant_id="tenantId",
                doc_id="docId",
                sha256="sha256",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.commit(tenant_id, doc_id, sha256=sha256, request_options=request_options)
        return _response.data

    async def download(
        self, tenant_id: str, doc_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.AsyncIterator[bytes]:
        """
        Parameters
        ----------
        tenant_id : str

        doc_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration. You can pass in configuration such as `chunk_size`, and more to customize the request and response.

        Returns
        -------
        typing.AsyncIterator[bytes]
            OK

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.download(
                tenant_id="tenantId",
                doc_id="docId",
            )


        asyncio.run(main())
        """
        async with self._raw_client.download(tenant_id, doc_id, request_options=request_options) as r:
            async for _chunk in r.data:
                yield _chunk

    async def thumbnail(
        self, tenant_id: str, doc_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.AsyncIterator[bytes]:
        """
        Parameters
        ----------
        tenant_id : str

        doc_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration. You can pass in configuration such as `chunk_size`, and more to customize the request and response.

        Returns
        -------
        typing.AsyncIterator[bytes]
            OK

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.thumbnail(
                tenant_id="tenantId",
                doc_id="docId",
            )


        asyncio.run(main())
        """
        async with self._raw_client.thumbnail(tenant_id, doc_id, request_options=request_options) as r:
            async for _chunk in r.data:
                yield _chunk

    async def upload_proxy(
        self, tenant_id: str, doc_id: str, *, file: core.File, request_options: typing.Optional[RequestOptions] = None
    ) -> DocumentsUploadProxyResponse:
        """
        This bounded origin-mediated fallback must only be used after documents.init returns upload.kind=proxy. Auto mode prefers a presigned object-store PUT whenever available. An upload token sends files only to the documents it started.

        Parameters
        ----------
        tenant_id : str

        doc_id : str

        file : core.File
            See core.File for more documentation

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsUploadProxyResponse
            OK

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.upload_proxy(
                tenant_id="tenantId",
                doc_id="docId",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.upload_proxy(tenant_id, doc_id, file=file, request_options=request_options)
        return _response.data

    async def import_from(
        self,
        tenant_id: str,
        *,
        source: DocumentsImportFromRequestSource,
        expected: typing.Optional[DocumentsImportFromRequestExpected] = OMIT,
        name: typing.Optional[str] = OMIT,
        folder_id: typing.Optional[str] = OMIT,
        metadata: typing.Optional[typing.Dict[str, typing.Any]] = OMIT,
        idempotency_key: typing.Optional[str] = OMIT,
        dedup_mode: typing.Optional[DocumentsImportFromRequestDedupMode] = OMIT,
        doc_id: typing.Optional[str] = OMIT,
        mode: typing.Optional[DocumentsImportFromRequestMode] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> DocumentsImportFrom200Response:
        """
        Default mode is synchronous and bounded: the response returns only after the transfer verified and committed (or failed). mode=async (connection sources only) answers 202 immediately and an in-process worker performs the transfer with leased, fenced retries; poll the document until ready/failed. The deployment import policy gates scheme, network range, and size; sources must declare a length. CloudPDF copies and owns the bytes — the source is never referenced in place. A 502 marks a retryable upstream failure: retry with the same idempotencyKey to resume the same document. URL sources are capabilities and never echoed back. Connection sources name operator-registered storage (bucket/prefix scope, allowed credential classes, and tenant bindings are deployment configuration); `revision` is provider-interpreted (S3 VersionId, GCS generation, Azure version id).

        Parameters
        ----------
        tenant_id : str

        source : DocumentsImportFromRequestSource
            Where CloudPDF pulls the bytes from. The two shapes differ in who supplies the authority to read, not in which storage vendor holds the file.

        expected : typing.Optional[DocumentsImportFromRequestExpected]
            Integrity pins, enforced when present. When absent, the server-observed values become authoritative.

        name : typing.Optional[str]
            What people call the document: shown in dashboards, searched and sorted by. 1 to 255 characters, no control characters, no leading or trailing whitespace. Names need not be unique.

        folder_id : typing.Optional[str]
            A folder id, or root for the top level.

        metadata : typing.Optional[typing.Dict[str, typing.Any]]

        idempotency_key : typing.Optional[str]
            Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.

        dedup_mode : typing.Optional[DocumentsImportFromRequestDedupMode]
            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.

        doc_id : typing.Optional[str]

        mode : typing.Optional[DocumentsImportFromRequestMode]
            sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsImportFrom200Response
            OK

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient
        from cloudpdf.documents import DocumentsImportFromRequestSource_Url

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.import_from(
                tenant_id="tenantId",
                source=DocumentsImportFromRequestSource_Url(
                    url="url",
                ),
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.import_from(
            tenant_id,
            source=source,
            expected=expected,
            name=name,
            folder_id=folder_id,
            metadata=metadata,
            idempotency_key=idempotency_key,
            dedup_mode=dedup_mode,
            doc_id=doc_id,
            mode=mode,
            request_options=request_options,
        )
        return _response.data

    async def init(
        self,
        tenant_id: str,
        *,
        size_bytes: int,
        content_sha256: str,
        name: typing.Optional[str] = OMIT,
        folder_id: typing.Optional[str] = OMIT,
        metadata: typing.Optional[typing.Dict[str, typing.Any]] = OMIT,
        idempotency_key: typing.Optional[str] = OMIT,
        dedup_mode: typing.Optional[DocumentsInitRequestDedupMode] = OMIT,
        doc_id: typing.Optional[str] = OMIT,
        upload_ttl_seconds: typing.Optional[int] = OMIT,
        upload_preference: typing.Optional[DocumentsInitRequestUploadPreference] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> DocumentsInitResponse:
        """
        With an upload token, the document goes into the token's folder with the token's metadata, whatever the request says; sizeBytes must be within the token's maxBytes, and the token makes at most maxFiles documents (403 after). docId, idempotencyKey and dedupMode reuse-existing are refused (400): each could reach a document the token didn't make.

        Parameters
        ----------
        tenant_id : str

        size_bytes : int

        content_sha256 : str

        name : typing.Optional[str]
            What people call the document: shown in dashboards, searched and sorted by. 1 to 255 characters, no control characters, no leading or trailing whitespace. Names need not be unique.

        folder_id : typing.Optional[str]
            A folder id, or root for the top level.

        metadata : typing.Optional[typing.Dict[str, typing.Any]]

        idempotency_key : typing.Optional[str]

        dedup_mode : typing.Optional[DocumentsInitRequestDedupMode]
            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.

        doc_id : typing.Optional[str]

        upload_ttl_seconds : typing.Optional[int]

        upload_preference : typing.Optional[DocumentsInitRequestUploadPreference]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DocumentsInitResponse
            OK

        Examples
        --------
        import asyncio

        from cloudpdf import AsyncCloudPDFClient

        client = AsyncCloudPDFClient(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.documents.init(
                tenant_id="tenantId",
                size_bytes=1,
                content_sha256="contentSha256",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.init(
            tenant_id,
            size_bytes=size_bytes,
            content_sha256=content_sha256,
            name=name,
            folder_id=folder_id,
            metadata=metadata,
            idempotency_key=idempotency_key,
            dedup_mode=dedup_mode,
            doc_id=doc_id,
            upload_ttl_seconds=upload_ttl_seconds,
            upload_preference=upload_preference,
            request_options=request_options,
        )
        return _response.data

    @property
    def layers(self):
        if self._layers is None:
            from .layers.client import AsyncLayersClient  # noqa: E402

            self._layers = AsyncLayersClient(client_wrapper=self._client_wrapper)
        return self._layers