pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/wire/rest/accounts.py

@@ -0,0 +1,512 @@
+"""The account doors' bodies: sign-in, keys, people, sign-up, SSO, mail, who a key is, policy."""
+
+from datetime import datetime
+from typing import Annotated, Literal, Self
+
+from pydantic import AwareDatetime, Field, model_validator
+
+from pinecall.domain.names import Env
+from pinecall.domain.person import Key, Member, MemberStatus, Role
+from pinecall.wire.frames import WireModel
+
+# ── people ──
+
+
+class MemberRow(WireModel):
+    """A member as every members door answers one: never a password nor a link."""
+
+    id: str
+    email: str
+    name: str
+    role: Role
+    agents: list[str]
+    status: MemberStatus
+    scopes: list[str]
+    operator: bool
+    # The production switch, or being an admin.
+    production: bool
+    verified: bool
+
+    @classmethod
+    def of(cls, member: Member) -> Self:
+        """The member as a row."""
+        return cls(
+            id=member.id,
+            email=member.email,
+            name=member.name,
+            role=member.role,
+            agents=sorted(member.agents),
+            status=member.status,
+            scopes=sorted(member.scopes),
+            operator=member.operator,
+            production=member.opens_production,
+            verified=member.verified,
+        )
+
+
+class MemberList(WireModel):
+    """GET /v1/members, the answer: every member of the org, oldest first."""
+
+    members: list[MemberRow]
+
+
+class InviteMemberRequest(WireModel):
+    """POST /v1/members: who, the role, the agents they see (none is every one), production."""
+
+    email: str
+    name: str
+    role: str
+    agents: list[str] = Field(default_factory=list[str])
+    production: bool = False
+
+
+class InvitationResponse(WireModel):
+    """An invitation or a reset: the member, the link's token once (null when only mailed)."""
+
+    member: MemberRow
+    token: str | None
+    expires_at: datetime | None
+    mailed: bool
+    # The card the token opens, on the box's public name: what a terminal prints, a letter carries.
+    link: str | None = None
+
+
+class ChangeMemberRequest(WireModel):
+    """PATCH /v1/members/{id}: what is named changes, what is left out stays."""
+
+    role: str | None = None
+    agents: list[str] | None = None
+    status: str | None = None
+    production: bool | None = None
+
+
+class AcceptInvitationRequest(WireModel):
+    """POST /v1/invitations/{token}: the password chosen, and what the first key is called."""
+
+    password: str
+    device: str | None = None
+
+
+# ── keys ──
+
+
+class KeyIssuedResponse(WireModel):
+    """Every door that mints a key: the key this once, and what it was written under."""
+
+    key: str
+    key_id: str
+    org: str
+    label: str | None
+    env: Env
+    scopes: list[str]
+    subject: str | None
+    name: str | None
+
+    @classmethod
+    def of(cls, key: Key, secret: str) -> Self:
+        """The key just minted, and its secret this once."""
+        return cls(
+            key=secret,
+            key_id=key.key_id,
+            org=key.org,
+            label=key.label,
+            env=key.env,
+            scopes=sorted(key.scopes),
+            subject=key.subject,
+            name=key.name,
+        )
+
+
+class FirstKeyResponse(WireModel):
+    """POST /v1/invitations/{token}: the member's first key, and the member now active."""
+
+    key: str
+    key_id: str
+    org: str
+    label: str | None
+    env: Env
+    scopes: list[str]
+    subject: str | None
+    name: str | None
+    member: MemberRow
+
+
+class OrgMadeResponse(WireModel):
+    """POST /v1/signup/verify: the admin's key, the org's slug, and the code for the console."""
+
+    key: str
+    key_id: str
+    org: str
+    label: str | None
+    env: Env
+    scopes: list[str]
+    subject: str | None
+    name: str | None
+    slug: str
+    member: MemberRow
+    code: str
+    code_expires_at: float
+
+
+class CreateKeyRequest(WireModel):
+    """POST /v1/keys: a server's token, named, for one world; fewer scopes, and an end, if asked."""
+
+    label: str
+    env: str
+    # None is every scope a server's token opens; a list is some of them.
+    scopes: list[str] | None = None
+    # None never expires.
+    expires_at: AwareDatetime | None = None
+
+
+class KeyRow(WireModel):
+    """GET /v1/keys, one row: a key by its fingerprint, never the key."""
+
+    fingerprint: str
+    label: str | None
+    kind: Literal["person", "server"]
+    # Only a server's token is bound to one world.
+    env: Env | None
+    name: str | None
+    created_by: str | None
+    created_at: datetime
+    last_used_at: datetime | None
+    revoked_at: datetime | None
+    scopes: list[str]
+    expires_at: datetime | None = None
+
+
+class RevokeKeyResponse(WireModel):
+    """POST /v1/keys/{fingerprint}/revoke, the answer."""
+
+    fingerprint: str
+    revoked: bool
+
+
+# ── who a key is ──
+
+
+class WhoamiResponse(WireModel):
+    """GET /v1/whoami: whose key this is and what it opens; never the key nor its hash."""
+
+    org: str
+    # None only when the org's row is gone.
+    slug: str | None
+    key_id: str
+    label: str | None
+    # The world this request acts in.
+    env: Env
+    scopes: list[str]
+    subject: str | None
+    name: str | None
+    # The one name a person carries into every org; None for a server's token.
+    email: str | None
+    operator: bool
+    # A person of the box inside an org they are no member of.
+    visiting: bool
+    production: bool
+
+
+class BoxIdentityResponse(WireModel):
+    """GET /v1/ops/whoami: the box an operator's key opens, and who holds the key."""
+
+    operator: bool
+    version: str
+    domain: str | None
+    # None for the box's own key.
+    name: str | None
+    org: str | None
+
+
+class BrandRow(WireModel):
+    """What the box's pages and letters are called and painted with."""
+
+    name: str
+    logo_url: str | None
+    accent: str
+
+
+class GatewayInfoResponse(WireModel):
+    """GET /.well-known/pinecall: what a sign-in page reads before anybody holds a key."""
+
+    version: str
+    signup: bool
+    # 0 is no rule.
+    min_password: int
+    # Whether the box itself can post a letter; an org's own mailbox is not counted.
+    mail: bool
+    brand: BrandRow
+    google: bool
+
+
+# ── signing in ──
+
+
+class SignInRequest(WireModel):
+    """POST /v1/login: an address and a password, the org when there are several, or a code."""
+
+    org: str | None = None
+    email: str | None = None
+    password: str | None = None
+    code: str | None = None
+    # What the minted key is called in the org's list, so it is revoked on its own.
+    device: str | None = None
+
+
+class SignInOrgsRequest(WireModel):
+    """POST /v1/login/orgs: the address and the password, to list what they open."""
+
+    email: str
+    password: str
+
+
+class SignInOrgRow(WireModel):
+    """One org a password opens, and the person's role there."""
+
+    org: str
+    slug: str
+    name: str
+    role: Role
+
+
+class SignInOrgsResponse(WireModel):
+    """POST /v1/login/orgs, the answer: the orgs, oldest first."""
+
+    orgs: list[SignInOrgRow]
+
+
+class OrgOfPersonRow(WireModel):
+    """GET /v1/login/orgs, one org: the role there, and whether this key is the one opening it."""
+
+    org: str
+    slug: str | None
+    name: str | None
+    # A role, or "operator" for an org of the box a person runs and is no member of.
+    role: str
+    status: MemberStatus
+    here: bool
+    member: bool
+
+
+class OrgsOfPersonResponse(WireModel):
+    """GET /v1/login/orgs, the answer: every org the key's person may open, oldest first."""
+
+    orgs: list[OrgOfPersonRow]
+
+
+class SwitchOrgRequest(WireModel):
+    """POST /v1/login/org: the org to be signed into, by id or slug."""
+
+    org: str
+
+
+class MintCodeResponse(WireModel):
+    """A one-use word and when it dies, in epoch seconds: a login code, a terminal's pairing."""
+
+    code: str
+    expires_at: float
+
+
+class ForgotPasswordRequest(WireModel):
+    """POST /v1/login/reset: the address whose password was forgotten."""
+
+    email: str
+
+
+class EmptyResponse(WireModel):
+    """An answer whose status says everything: `{}`."""
+
+
+class OpenPairingRequest(WireModel):
+    """POST /v1/login/pairings: what the terminal calls itself."""
+
+    device: str | None = None
+
+
+class PairingStatusResponse(WireModel):
+    """GET /v1/login/pairings/{code}: which terminal a browser is about to sign in."""
+
+    device: str | None
+    expires_at: float
+    answered: bool
+
+
+class PairingApprovedResponse(WireModel):
+    """POST /v1/login/pairings/{code}: the terminal signed in, and into which org."""
+
+    device: str | None
+    org: str
+    # What the page says it signed in to: the org's name, as a person knows it.
+    org_name: str
+
+
+class KeyCollectedResponse(WireModel):
+    """GET /v1/login/pairings/{code}/key: the terminal's key, once."""
+
+    key: str
+
+
+# ── sign-up ──
+
+
+class SignupRequest(WireModel):
+    """POST /v1/signup: the org's slug and name, the person, and their password."""
+
+    org: str
+    name: str | None = None
+    email: str
+    person: str
+    password: str
+    device: str | None = None
+
+
+class CodeMailedResponse(WireModel):
+    """POST /v1/signup, the answer: where the code went and when it dies; never the code."""
+
+    email: str
+    code_expires_at: float
+
+
+class VerifySignupRequest(WireModel):
+    """POST /v1/signup/verify: the address and the six digits mailed to it."""
+
+    email: str
+    code: str
+    device: str | None = None
+
+
+class ResendCodeRequest(WireModel):
+    """POST /v1/signup/resend: the address a sign-up is waiting on."""
+
+    email: str
+
+
+# ── the org's identity provider ──
+
+
+class OrgSsoRequest(WireModel):
+    """PUT /v1/org/sso: the provider whole, its client secret included every time."""
+
+    issuer: str
+    client_id: str
+    client_secret: str
+    domains: list[str]
+    # Who the provider seats unasked; None seats nobody it was not told to.
+    role: str | None = None
+    required: bool = False
+
+
+class SsoDomainProof(WireModel):
+    """One domain of the org's SSO: the TXT record that proves it the org's, and whether seen."""
+
+    domain: str
+    txt: str
+    verified: bool
+
+
+class OrgSsoResponse(WireModel):
+    """GET /v1/org/sso: the org's provider, never its secret, and the URI to register there."""
+
+    configured: bool
+    issuer: str | None
+    client_id: str | None
+    domains: list[str]
+    role: Role | None
+    required: bool
+    redirect_uri: str
+    # Each domain's proof: discovery offers the provider for a verified domain alone.
+    proofs: list[SsoDomainProof] = Field(default_factory=list[SsoDomainProof])
+
+
+class DiscoverSsoRequest(WireModel):
+    """POST /v1/login/sso/discover: the address whose domain is asked about."""
+
+    email: str
+
+
+class SsoOrgRow(WireModel):
+    """An org that signs in an address's domain with its provider."""
+
+    org: str
+    slug: str
+    name: str
+
+
+class DiscoverSsoResponse(WireModel):
+    """POST /v1/login/sso/discover, the answer: the orgs, oldest first."""
+
+    orgs: list[SsoOrgRow]
+
+
+# ── the org's mailbox ──
+
+
+class OrgMailRequest(WireModel):
+    """PUT /v1/org/mail: the org's SMTP account, its password included every time."""
+
+    host: str
+    port: int
+    security: str = "starttls"
+    # Empty for a relay that asks for nothing.
+    username: str = ""
+    password: str = ""
+    sender: str = Field(alias="from")
+
+
+class OrgMailResponse(WireModel):
+    """GET /v1/org/mail: the org's mailbox, never its password, and how its last letter went."""
+
+    configured: bool
+    host: str | None
+    port: int | None
+    security: str | None
+    username: str | None
+    sender: str | None = Field(alias="from")
+    verified_at: datetime | None
+    last_error: str | None
+
+
+class SendTestLetterRequest(WireModel):
+    """POST /v1/org/mail/test: who the test letter goes to."""
+
+    to: str
+
+
+class SendTestLetterResponse(WireModel):
+    """POST /v1/org/mail/test, the answer: whether it went, and what the server said if not."""
+
+    sent: bool
+    error: str | None
+
+
+class CallingHours(WireModel):
+    """The hours of the called number's own day a call may ring: from, until (exclusive)."""
+
+    from_: Annotated[int, Field(ge=0, le=23)] = Field(alias="from")
+    until: Annotated[int, Field(ge=1, le=24)]
+
+    @model_validator(mode="after")
+    def _a_window(self) -> Self:
+        if self.from_ >= self.until:
+            raise ValueError(f"calling hours from {self.from_} until {self.until} leave no hour")
+        return self
+
+
+class OrgPolicy(WireModel):
+    """GET and PUT /v1/org/policy: the org's compliance settings, replaced whole."""
+
+    retention_days: Annotated[int, Field(gt=0)] | None = None
+    calling_hours: CallingHours | None = None
+    per_number_day: Annotated[int, Field(gt=0)] | None = None
+    consent_everywhere: bool = False
+    # An outbound call's opening sentence: null is the platform's, "" is none.
+    disclosure: Annotated[str, Field(max_length=500)] | None = None
+    recording_notice: bool = True
+
+
+class OrgPolicyRow(WireModel):
+    """GET /v1/org/policy: the settings, who set them last, and when."""
+
+    policy: OrgPolicy
+    set_by: str | None
+    set_at: float | None

pinecall/wire/rest/agents.py

@@ -0,0 +1,172 @@
+"""The bodies of the agent doors: agents held, sockets, the line, judging, pipeline, widget."""
+
+from typing import Literal
+
+from pinecall.domain.names import Channel, Env
+from pinecall.wire.frames import WireModel
+from pinecall.wire.parts import GreetingConfig, WidgetTheme
+from pinecall.wire.rest.numbers import LegTrunk
+from pinecall.wire.rest.providers import ProviderRow
+
+# ── the agents an org holds, and whose terminal a ring lands in ──
+
+
+class ScopeHolder(WireModel):
+    """A scope by its member id and email; both null for the org's own."""
+
+    holder: str | None
+    name: str | None
+
+
+class AgentRow(WireModel):
+    """An agent some socket of the org holds, the doors it answers, and whose scope."""
+
+    slug: str
+    channels: list[Channel]
+    holder: ScopeHolder | None = None
+
+
+class AgentList(WireModel):
+    """The org's held agents in the request's world."""
+
+    agents: list[AgentRow]
+
+
+class AppRow(WireModel):
+    """One connected app socket and what it holds."""
+
+    app: str
+    agents: list[str]
+    env: Env
+    host: str | None
+    address: str | None
+    sdk: str | None
+    holder: ScopeHolder | None
+    connected_at: float
+
+
+class AppList(WireModel):
+    """The app sockets of the org this key may see."""
+
+    apps: list[AppRow]
+
+
+class StopAppResponse(WireModel):
+    """A stop answered."""
+
+    app: str
+    stopped: bool
+
+
+class RingTarget(WireModel):
+    """Whose terminal a ring at the agent lands in, and who else could take it."""
+
+    agent: str
+    env: Env
+    held: bool
+    holding: ScopeHolder | None = None
+    yours: bool
+    waiting: list[ScopeHolder]
+    calling: list[str]
+
+
+class DeveloperPhones(WireModel):
+    """The phone a developer calls from."""
+
+    number: str
+
+
+class TestNumber(WireModel):
+    """A production number and the agent it reaches."""
+
+    number: str
+    agent: str
+
+
+class TestNumbers(WireModel):
+    """The person's own phones, and the production numbers they can dial to test."""
+
+    calling: list[str]
+    numbers: list[TestNumber]
+
+
+class RingHandoff(WireModel):
+    """Where a production ring goes: a developer's scope and its fleet, or nowhere (null)."""
+
+    holder: str | None = None
+    fleet: str | None = None
+    # Where the sandbox has a LiveKit of its own: the ring is dialled to its SIP through this.
+    trunk: LegTrunk | None = None
+
+
+class JudgingSettings(WireModel):
+    """Whether an org's calls are judged at hang-up, and the ceiling per call."""
+
+    on: bool
+    ceiling_usd: float | None
+
+
+class JudgingRequest(WireModel):
+    """JudgingSettings on or off."""
+
+    on: bool
+
+
+class HoldAudio(WireModel):
+    """What a caller hears while a tool runs: the box's melody, silence, or the org's own clip."""
+
+    played: Literal["default", "off", "custom"]
+    sha256: str | None = None
+    seconds: float | None = None
+    name: str | None = None
+
+
+class PlayedRequest(WireModel):
+    """PUT /v1/agents/{slug}/pipeline/hold-audio/played: the box's melody back, or silence."""
+
+    played: Literal["default", "off"]
+
+
+class PipelineStage(WireModel):
+    """One stage as the next call would run it: the vendor, its model, the voice or language."""
+
+    vendor: str
+    model: str | None = None
+    voice_id: str | None = None
+    language: str | None = None
+
+
+class Measured(WireModel):
+    """One latency over the agent's recent calls: livekit's name, the median, the turns."""
+
+    name: str
+    seconds: float
+    turns: int
+
+
+class PipelineReport(WireModel):
+    """GET /v1/agents/{slug}/pipeline: what it hears, decides and speaks with, and how fast."""
+
+    agent: str
+    hears: PipelineStage
+    decides: PipelineStage
+    speaks: PipelineStage
+    greeting: GreetingConfig | None
+    voices: list[str]
+    providers: list[ProviderRow]
+    defaults: dict[str, str]
+    models: dict[str, list[str]]
+    calls: int
+    medians: list[Measured]
+    unavailable_reasons: dict[str, str]
+
+
+class WidgetSettings(WireModel):
+    """GET and PUT /v1/agents/{slug}/widget: how the widget presents the agent, per world."""
+
+    title: str | None = None
+    tagline: str | None = None
+    greeting: str | None = None
+    accent: str | None = None
+    autostart: bool = False
+    theme: WidgetTheme | None = None