workos 1.5.1__py3-none-any.whl → 5.38.0__py3-none-any.whl

workos/types/events/event_model.py

@@ -0,0 +1,103 @@
+from typing import Generic, Literal, TypeVar
+from workos.types.user_management import OrganizationMembership, User
+from workos.types.workos_model import WorkOSModel
+from workos.types.directory_sync.directory_group import DirectoryGroup
+from workos.types.directory_sync.directory_user import DirectoryUser
+from workos.types.events.authentication_payload import (
+    AuthenticationEmailVerificationSucceededPayload,
+    AuthenticationMagicAuthFailedPayload,
+    AuthenticationMagicAuthSucceededPayload,
+    AuthenticationMfaSucceededPayload,
+    AuthenticationOauthFailedPayload,
+    AuthenticationOauthSucceededPayload,
+    AuthenticationPasswordFailedPayload,
+    AuthenticationPasswordSucceededPayload,
+    AuthenticationSsoFailedPayload,
+    AuthenticationSsoSucceededPayload,
+)
+from workos.types.events.connection_payload_with_legacy_fields import (
+    ConnectionPayloadWithLegacyFields,
+)
+from workos.types.events.directory_group_membership_payload import (
+    DirectoryGroupMembershipPayload,
+)
+from workos.types.events.directory_group_with_previous_attributes import (
+    DirectoryGroupWithPreviousAttributes,
+)
+from workos.types.events.directory_payload import DirectoryPayload
+from workos.types.events.directory_payload_with_legacy_fields import (
+    DirectoryPayloadWithLegacyFields,
+    DirectoryPayloadWithLegacyFieldsForEventsApi,
+)
+from workos.types.events.directory_user_with_previous_attributes import (
+    DirectoryUserWithPreviousAttributes,
+)
+from workos.types.events.organization_domain_verification_failed_payload import (
+    OrganizationDomainVerificationFailedPayload,
+)
+
+from workos.types.events.session_payload import (
+    SessionCreatedPayload,
+    SessionRevokedPayload,
+)
+from workos.types.organizations.organization_common import OrganizationCommon
+from workos.types.organization_domains import OrganizationDomain
+from workos.types.roles.role import EventRole
+from workos.types.sso.connection import Connection
+from workos.types.user_management.email_verification import (
+    EmailVerificationCommon,
+)
+from workos.types.user_management.invitation import InvitationCommon
+from workos.types.user_management.magic_auth import MagicAuthCommon
+from workos.types.user_management.password_reset import PasswordResetCommon
+
+
+EventPayload = TypeVar(
+    "EventPayload",
+    AuthenticationEmailVerificationSucceededPayload,
+    AuthenticationMagicAuthFailedPayload,
+    AuthenticationMagicAuthSucceededPayload,
+    AuthenticationMfaSucceededPayload,
+    AuthenticationOauthFailedPayload,
+    AuthenticationOauthSucceededPayload,
+    AuthenticationPasswordFailedPayload,
+    AuthenticationPasswordSucceededPayload,
+    AuthenticationSsoFailedPayload,
+    AuthenticationSsoSucceededPayload,
+    Connection,
+    ConnectionPayloadWithLegacyFields,
+    DirectoryPayload,
+    DirectoryPayloadWithLegacyFields,
+    # TODO: Remove once merged with DirectoryPayloadWithLegacyFields in next major release.
+    DirectoryPayloadWithLegacyFieldsForEventsApi,
+    DirectoryGroup,
+    DirectoryGroupWithPreviousAttributes,
+    DirectoryUser,
+    DirectoryUserWithPreviousAttributes,
+    DirectoryGroupMembershipPayload,
+    EmailVerificationCommon,
+    EventRole,
+    InvitationCommon,
+    MagicAuthCommon,
+    OrganizationCommon,
+    OrganizationDomain,
+    OrganizationDomainVerificationFailedPayload,
+    OrganizationMembership,
+    PasswordResetCommon,
+    SessionCreatedPayload,
+    SessionRevokedPayload,
+    User,
+)
+
+
+class EventModel(WorkOSModel, Generic[EventPayload]):
+    # TODO: fix these docs
+    """Representation of an Event returned from the Events API or via Webhook.
+    Attributes:
+        OBJECT_FIELDS (list): List of fields an Event is comprised of.
+    """
+
+    id: str
+    object: Literal["event"]
+    data: EventPayload
+    created_at: str

workos/types/events/event_type.py

@@ -0,0 +1,59 @@
+from typing import Literal, TypeVar
+
+# README
+# When adding a new event type, ensure a new event class is created
+# and added to the Event class union type in event.py.
+
+EventType = Literal[
+    "authentication.email_verification_succeeded",
+    "authentication.magic_auth_failed",
+    "authentication.magic_auth_succeeded",
+    "authentication.mfa_succeeded",
+    "authentication.oauth_failed",
+    "authentication.oauth_succeeded",
+    "authentication.password_failed",
+    "authentication.password_succeeded",
+    "authentication.sso_failed",
+    "authentication.sso_succeeded",
+    "connection.activated",
+    "connection.deactivated",
+    "connection.deleted",
+    "dsync.activated",
+    "dsync.deleted",
+    "dsync.group.created",
+    "dsync.group.deleted",
+    "dsync.group.updated",
+    "dsync.user.created",
+    "dsync.user.deleted",
+    "dsync.user.updated",
+    "dsync.group.user_added",
+    "dsync.group.user_removed",
+    "email_verification.created",
+    "invitation.accepted",
+    "invitation.created",
+    "invitation.revoked",
+    "magic_auth.created",
+    "organization.created",
+    "organization.deleted",
+    "organization.updated",
+    "organization_domain.verification_failed",
+    "organization_domain.verified",
+    "organization_domain.created",
+    "organization_domain.deleted",
+    "organization_domain.updated",
+    "organization_membership.created",
+    "organization_membership.deleted",
+    "organization_membership.updated",
+    "password_reset.created",
+    "password_reset.succeeded",
+    "role.created",
+    "role.deleted",
+    "role.updated",
+    "session.created",
+    "session.revoked",
+    "user.created",
+    "user.deleted",
+    "user.updated",
+]
+
+EventTypeDiscriminator = TypeVar("EventTypeDiscriminator", bound=EventType)

workos/types/events/list_filters.py

@@ -0,0 +1,10 @@
+from typing import Optional, Sequence
+from workos.types.events import EventType
+from workos.types.list_resource import ListArgs
+
+
+class EventsListFilters(ListArgs, total=False):
+    events: Sequence[EventType]
+    organization_id: Optional[str]
+    range_start: Optional[str]
+    range_end: Optional[str]

workos/types/events/organization_domain_verification_failed_payload.py

@@ -0,0 +1,14 @@
+from typing import Literal
+from workos.types.workos_model import WorkOSModel
+from workos.types.organization_domains import OrganizationDomain
+from workos.typing.literals import LiteralOrUntyped
+
+
+class OrganizationDomainVerificationFailedPayload(WorkOSModel):
+    reason: LiteralOrUntyped[
+        Literal[
+            "domain_verification_period_expired",
+            "domain_verified_by_other_organization",
+        ]
+    ]
+    organization_domain: OrganizationDomain

workos/types/events/previous_attributes.py

@@ -0,0 +1,3 @@
+from typing import Any, Mapping
+
+PreviousAttributes = Mapping[str, Any]

workos/types/events/session_payload.py

@@ -0,0 +1,27 @@
+from typing import Literal, Optional
+from workos.types.workos_model import WorkOSModel
+from workos.types.user_management.impersonator import Impersonator
+
+
+class SessionCreatedPayload(WorkOSModel):
+    object: Literal["session"]
+    id: str
+    impersonator: Optional[Impersonator] = None
+    ip_address: Optional[str] = None
+    organization_id: Optional[str] = None
+    user_agent: Optional[str] = None
+    user_id: str
+    created_at: str
+    updated_at: str
+
+
+class SessionRevokedPayload(WorkOSModel):
+    object: Literal["session"]
+    id: str
+    impersonator: Optional[Impersonator] = None
+    ip_address: Optional[str] = None
+    organization_id: Optional[str] = None
+    user_agent: Optional[str] = None
+    user_id: str
+    created_at: str
+    updated_at: str

workos/types/feature_flags/__init__.py

@@ -0,0 +1,3 @@
+from workos.types.feature_flags.feature_flag import FeatureFlag
+
+__all__ = ["FeatureFlag"]

workos/types/feature_flags/feature_flag.py

@@ -0,0 +1,12 @@
+from typing import Literal, Optional
+from workos.types.workos_model import WorkOSModel
+
+
+class FeatureFlag(WorkOSModel):
+    id: str
+    object: Literal["feature_flag"]
+    slug: str
+    name: str
+    description: Optional[str]
+    created_at: str
+    updated_at: str

workos/types/feature_flags/list_filters.py

@@ -0,0 +1,5 @@
+from workos.types.list_resource import ListArgs
+
+
+class FeatureFlagListFilters(ListArgs, total=False):
+    pass

workos/types/fga/__init__.py

@@ -0,0 +1,5 @@
+from .check import *
+from .authorization_resource_types import *
+from .authorization_resources import *
+from .warrant import *
+from .warnings import *

workos/types/fga/authorization_resource_types.py

@@ -0,0 +1,9 @@
+from typing import Any, Mapping, Optional
+
+from workos.types.workos_model import WorkOSModel
+
+
+class AuthorizationResourceType(WorkOSModel):
+    type: str
+    relations: Mapping[str, Any]
+    created_at: Optional[str] = None

workos/types/fga/authorization_resources.py

@@ -0,0 +1,10 @@
+from typing import Any, Mapping, Optional
+
+from workos.types.workos_model import WorkOSModel
+
+
+class AuthorizationResource(WorkOSModel):
+    resource_type: str
+    resource_id: str
+    meta: Optional[Mapping[str, Any]] = None
+    created_at: Optional[str] = None

workos/types/fga/check.py

@@ -0,0 +1,51 @@
+from typing import Any, Literal, Mapping, Optional, Sequence, TypedDict
+
+from workos.types.workos_model import WorkOSModel
+from workos.typing.literals import LiteralOrUntyped
+
+from .warnings import FGAWarning
+from .warrant import Subject, SubjectInput
+
+CheckOperation = Literal["any_of", "all_of", "batch"]
+
+
+class WarrantCheckInput(TypedDict, total=False):
+    resource_type: str
+    resource_id: str
+    relation: str
+    subject: SubjectInput
+    context: Optional[Mapping[str, Any]]
+
+
+class WarrantCheck(WorkOSModel):
+    resource_type: str
+    resource_id: str
+    relation: str
+    subject: Subject
+    context: Optional[Mapping[str, Any]] = None
+
+
+class DecisionTreeNode(WorkOSModel):
+    check: WarrantCheck
+    decision: str
+    processing_time: int
+    children: Optional[Sequence["DecisionTreeNode"]] = None
+    policy: Optional[str] = None
+
+
+class DebugInfo(WorkOSModel):
+    processing_time: int
+    decision_tree: DecisionTreeNode
+
+
+CheckResult = Literal["authorized", "not_authorized"]
+
+
+class CheckResponse(WorkOSModel):
+    result: LiteralOrUntyped[CheckResult]
+    is_implicit: bool
+    debug_info: Optional[DebugInfo] = None
+    warnings: Optional[Sequence[FGAWarning]] = None
+
+    def authorized(self) -> bool:
+        return self.result == "authorized"

workos/types/fga/list_filters.py

@@ -0,0 +1,24 @@
+from typing import Mapping, Optional, Any
+
+from workos.types.list_resource import ListArgs
+
+
+class AuthorizationResourceListFilters(ListArgs, total=False):
+    resource_type: Optional[str]
+    search: Optional[str]
+
+
+class WarrantListFilters(ListArgs, total=False):
+    resource_type: Optional[str]
+    resource_id: Optional[str]
+    relation: Optional[str]
+    subject_type: Optional[str]
+    subject_id: Optional[str]
+    subject_relation: Optional[str]
+    warrant_token: Optional[str]
+
+
+class WarrantQueryListFilters(ListArgs, total=False):
+    q: Optional[str]
+    context: Optional[Mapping[str, Any]]
+    warrant_token: Optional[str]

workos/types/fga/warnings.py

@@ -0,0 +1,33 @@
+from typing import Sequence, Union, Any, Dict, Literal
+from typing_extensions import Annotated
+
+from pydantic import BeforeValidator
+from pydantic_core.core_schema import ValidationInfo
+
+from workos.types.workos_model import WorkOSModel
+
+
+class FGABaseWarning(WorkOSModel):
+    code: str
+    message: str
+
+
+class MissingContextKeysWarning(FGABaseWarning):
+    code: Literal["missing_context_keys"]
+    keys: Sequence[str]
+
+
+def fga_warning_dispatch_validator(
+    value: Dict[str, Any], info: ValidationInfo
+) -> FGABaseWarning:
+    if value.get("code") == "missing_context_keys":
+        return MissingContextKeysWarning.model_validate(value)
+
+    # Fallback to the base warning model
+    return FGABaseWarning.model_validate(value)
+
+
+FGAWarning = Annotated[
+    Union[MissingContextKeysWarning, FGABaseWarning],
+    BeforeValidator(fga_warning_dispatch_validator),
+]

workos/types/fga/warrant.py

@@ -0,0 +1,49 @@
+from typing import Literal, Mapping, Optional, Any
+from typing_extensions import TypedDict
+
+from workos.types.workos_model import WorkOSModel
+
+
+class SubjectInput(TypedDict, total=False):
+    resource_type: str
+    resource_id: str
+    relation: Optional[str]
+
+
+class Subject(WorkOSModel):
+    resource_type: str
+    resource_id: str
+    relation: Optional[str] = None
+
+
+class Warrant(WorkOSModel):
+    resource_type: str
+    resource_id: str
+    relation: str
+    subject: Subject
+    policy: Optional[str] = None
+
+
+class WriteWarrantResponse(WorkOSModel):
+    warrant_token: str
+
+
+WarrantWriteOperation = Literal["create", "delete"]
+
+
+class WarrantWrite(TypedDict, total=False):
+    op: WarrantWriteOperation
+    resource_type: str
+    resource_id: str
+    relation: str
+    subject: SubjectInput
+    policy: Optional[str]
+
+
+class WarrantQueryResult(WorkOSModel):
+    resource_type: str
+    resource_id: str
+    relation: str
+    warrant: Warrant
+    is_implicit: bool
+    meta: Optional[Mapping[str, Any]] = None

workos/types/list_resource.py

@@ -0,0 +1,198 @@
+from pydantic import BaseModel, Field
+from typing import (
+    Any,
+    Awaitable,
+    AsyncIterator,
+    Dict,
+    Literal,
+    Mapping,
+    Sequence,
+    Tuple,
+    TypeVar,
+    Generic,
+    Callable,
+    Iterator,
+    Optional,
+    Union,
+    cast,
+)
+from typing_extensions import Required, TypedDict
+from workos.types.directory_sync import (
+    Directory,
+    DirectoryGroup,
+    DirectoryUserWithGroups,
+)
+from workos.types.events import Event
+from workos.types.feature_flags import FeatureFlag
+from workos.types.fga import (
+    Warrant,
+    AuthorizationResource,
+    AuthorizationResourceType,
+    WarrantQueryResult,
+)
+from workos.types.mfa import AuthenticationFactor
+from workos.types.organizations import Organization
+from workos.types.sso import ConnectionWithDomains
+from workos.types.user_management import Invitation, OrganizationMembership, User
+from workos.types.user_management.session import Session as UserManagementSession
+from workos.types.vault import ObjectDigest
+from workos.types.workos_model import WorkOSModel
+from workos.utils.request_helper import DEFAULT_LIST_RESPONSE_LIMIT
+
+ListableResource = TypeVar(
+    # add all possible generics of List Resource
+    "ListableResource",
+    AuthenticationFactor,
+    ConnectionWithDomains,
+    Directory,
+    DirectoryGroup,
+    DirectoryUserWithGroups,
+    Event,
+    FeatureFlag,
+    Invitation,
+    Organization,
+    OrganizationMembership,
+    AuthorizationResource,
+    AuthorizationResourceType,
+    User,
+    UserManagementSession,
+    ObjectDigest,
+    Warrant,
+    WarrantQueryResult,
+)
+
+
+class ListAfterMetadata(BaseModel):
+    after: Optional[str] = None
+
+
+class ListMetadata(ListAfterMetadata):
+    before: Optional[str] = None
+
+
+ListMetadataType = TypeVar("ListMetadataType", ListAfterMetadata, ListMetadata)
+
+
+class ListPage(WorkOSModel, Generic[ListableResource]):
+    object: Literal["list"]
+    data: Sequence[ListableResource]
+    list_metadata: ListMetadata
+
+
+class ListArgs(TypedDict, total=False):
+    before: Optional[str]
+    after: Optional[str]
+    limit: Required[int]
+    order: Optional[Literal["asc", "desc"]]
+
+
+ListAndFilterParams = TypeVar("ListAndFilterParams", bound=ListArgs)
+
+
+class WorkOSListResource(
+    WorkOSModel,
+    Generic[ListableResource, ListAndFilterParams, ListMetadataType],
+):
+    object: Literal["list"]
+    data: Sequence[ListableResource]
+    list_metadata: ListMetadataType
+
+    # TODO: Fix type hinting for list_method to support both sync and async
+    list_method: Union[
+        Callable[
+            ...,
+            "WorkOSListResource[ListableResource, ListAndFilterParams, ListMetadataType]",
+        ],
+        Callable[
+            ...,
+            "Awaitable[WorkOSListResource[ListableResource, ListAndFilterParams, ListMetadataType]]",
+        ],
+    ] = Field(exclude=True)
+    list_args: ListAndFilterParams = Field(exclude=True)
+
+    def _parse_params(
+        self, limit_override: Optional[int] = None
+    ) -> Tuple[Dict[str, Union[int, str, None]], Mapping[str, Any]]:
+        fixed_pagination_params = cast(
+            # Type hints consider this a mismatch because it assume the dictionary is dict[str, int]
+            Dict[str, Union[int, str, None]],
+            {
+                "limit": limit_override or self.list_args["limit"],
+            },
+        )
+        if "order" in self.list_args:
+            fixed_pagination_params["order"] = self.list_args["order"]
+
+        # Omit common list parameters
+        filter_params = {
+            k: v
+            for k, v in self.list_args.items()
+            if k not in {"order", "limit", "before", "after"}
+        }
+
+        return fixed_pagination_params, filter_params
+
+    # Pydantic uses a custom `__iter__` method to support casting BaseModels
+    # to dictionaries. e.g. dict(model).
+    # As we want to support `for item in page`, this is inherently incompatible
+    # with the default pydantic behaviour. It is not possible to support both
+    # use cases at once. Fortunately, this is not a big deal as all other pydantic
+    # methods should continue to work as expected as there is an alternative method
+    # to cast a model to a dictionary, model.dict(), which is used internally
+    # by pydantic.
+    def __iter__(self) -> Iterator[ListableResource]:  # type: ignore
+        next_page: WorkOSListResource[
+            ListableResource, ListAndFilterParams, ListMetadataType
+        ]
+        after = self.list_metadata.after
+        fixed_pagination_params, filter_params = self._parse_params(
+            # Singe we're auto-paginating, ignore the original limit and use the default
+            limit_override=DEFAULT_LIST_RESPONSE_LIMIT
+        )
+        index: int = 0
+
+        while True:
+            if index >= len(self.data):
+                if after is not None:
+                    # TODO: Fix type hinting for list_method to support both sync and async
+                    # We use a union to support both sync and async methods,
+                    # but when we get to the particular implementation, it
+                    # doesn't know which one it is. It's safe, but should be fixed.
+                    next_page = self.list_method(
+                        after=after, **fixed_pagination_params, **filter_params
+                    )  # type: ignore
+                    self.data = next_page.data
+                    after = next_page.list_metadata.after
+                    index = 0
+                    continue
+                else:
+                    return
+            yield self.data[index]
+            index += 1
+
+    async def __aiter__(self) -> AsyncIterator[ListableResource]:
+        next_page: WorkOSListResource[
+            ListableResource, ListAndFilterParams, ListMetadataType
+        ]
+        after = self.list_metadata.after
+        fixed_pagination_params, filter_params = self._parse_params()
+        index: int = 0
+
+        while True:
+            if index >= len(self.data):
+                if after is not None:
+                    # TODO: Fix type hinting for list_method to support both sync and async
+                    # We use a union to support both sync and async methods,
+                    # but when we get to the particular implementation, it
+                    # doesn't know which one it is. It's safe, but should be fixed.
+                    next_page = await self.list_method(
+                        after=after, **fixed_pagination_params, **filter_params
+                    )  # type: ignore
+                    self.data = next_page.data
+                    after = next_page.list_metadata.after
+                    index = 0
+                    continue
+                else:
+                    return
+            yield self.data[index]
+            index += 1

workos/types/metadata.py

@@ -0,0 +1,4 @@
+from typing import Dict
+
+
+Metadata = Dict[str, str]

workos/types/mfa/__init__.py

@@ -0,0 +1,5 @@
+from .authentication_challenge_verification_response import *
+from .authentication_challenge import *
+from .authentication_factor_totp_and_challenge_response import *
+from .authentication_factor import *
+from .enroll_authentication_factor_type import *

workos/types/mfa/authentication_challenge.py

@@ -0,0 +1,14 @@
+from typing import Literal, Optional
+from workos.types.workos_model import WorkOSModel
+
+
+class AuthenticationChallenge(WorkOSModel):
+    """Representation of a MFA Challenge Response as returned by WorkOS through the MFA feature."""
+
+    object: Literal["authentication_challenge"]
+    id: str
+    created_at: str
+    updated_at: str
+    expires_at: Optional[str] = None
+    code: Optional[str] = None
+    authentication_factor_id: str

workos/types/mfa/authentication_challenge_verification_response.py

@@ -0,0 +1,9 @@
+from workos.types.workos_model import WorkOSModel
+from workos.types.mfa.authentication_challenge import AuthenticationChallenge
+
+
+class AuthenticationChallengeVerificationResponse(WorkOSModel):
+    """Representation of a WorkOS MFA Challenge Verification Response."""
+
+    challenge: AuthenticationChallenge
+    valid: bool