almanac-contracts 0.5.0__tar.gz

almanac_contracts-0.5.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: almanac-contracts
+Version: 0.5.0
+Summary: Shared wire contracts for Almanac clients and services.
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.8

almanac_contracts-0.5.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "almanac-contracts"
+version = "0.5.0"
+description = "Shared wire contracts for Almanac clients and services."
+requires-python = ">=3.12"
+dependencies = ["pydantic>=2.8"]
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["almanac_contracts*"]

almanac_contracts-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

almanac_contracts-0.5.0/src/almanac_contracts/__init__.py

@@ -0,0 +1 @@
+"""Stable contracts shared by Almanac's public edges."""

almanac_contracts-0.5.0/src/almanac_contracts/errors.py

@@ -0,0 +1,65 @@
+from typing import Literal
+
+ErrorCode = Literal[
+    "almanac_error",
+    "not_found",
+    "conflict",
+    "not_authenticated",
+    "forbidden",
+    "validation_failed",
+    "provider_unavailable",
+]
+
+
+class AlmanacError(Exception):
+    """Base class for product errors that can cross CLI and server edges."""
+
+    code: ErrorCode = "almanac_error"
+
+    def __init__(self, message: str, *, request_id: str | None = None):
+        super().__init__(message)
+        self.request_id = request_id
+
+
+class NotFoundError(AlmanacError):
+    code: ErrorCode = "not_found"
+
+    def __init__(self, resource: str, identifier: str):
+        super().__init__(f"{resource} not found: {identifier}")
+        self.resource = resource
+        self.identifier = identifier
+
+
+class ConflictError(AlmanacError):
+    code: ErrorCode = "conflict"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class ValidationFailed(AlmanacError):
+    code: ErrorCode = "validation_failed"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class NotAuthenticated(AlmanacError):
+    code: ErrorCode = "not_authenticated"
+
+    def __init__(self, message: str = "Missing or invalid credentials"):
+        super().__init__(message)
+
+
+class ForbiddenError(AlmanacError):
+    code: ErrorCode = "forbidden"
+
+    def __init__(self, message: str = "Insufficient permission"):
+        super().__init__(message)
+
+
+class ProviderUnavailable(AlmanacError):
+    code: ErrorCode = "provider_unavailable"
+
+    def __init__(self, message: str):
+        super().__init__(message)

almanac_contracts-0.5.0/src/almanac_contracts/hosted/__init__.py

@@ -0,0 +1,77 @@
+from almanac_contracts.hosted.api_keys import ApiKey, CreatedApiKey
+from almanac_contracts.hosted.billing import (
+    BillingPlanChange,
+    BillingPortal,
+    BillingPreview,
+    BillingState,
+)
+from almanac_contracts.hosted.jobs import (
+    Job,
+    JobEvent,
+    JobImportOutcome,
+    JobOutcome,
+    JobPageChange,
+    JobSourceChange,
+)
+from almanac_contracts.hosted.pages import (
+    Page,
+    PageRecord,
+    PageSearchResult,
+    PageSource,
+    PageSummary,
+)
+from almanac_contracts.hosted.sources import (
+    ImportItem,
+    Source,
+    SourceFolder,
+    SourceTree,
+    Upload,
+    UploadFilePlan,
+    UploadPlan,
+    UploadResult,
+    UploadTarget,
+)
+from almanac_contracts.hosted.topics import Topic, TopicSummary
+from almanac_contracts.hosted.wikis import Wiki
+from almanac_contracts.hosted.workspaces import (
+    Workspace,
+    WorkspaceInvitation,
+    WorkspaceMember,
+    WorkspaceMembers,
+)
+
+__all__ = [
+    "ApiKey",
+    "BillingPlanChange",
+    "BillingPortal",
+    "BillingPreview",
+    "BillingState",
+    "CreatedApiKey",
+    "Job",
+    "JobEvent",
+    "JobImportOutcome",
+    "JobOutcome",
+    "JobPageChange",
+    "JobSourceChange",
+    "ImportItem",
+    "Page",
+    "PageRecord",
+    "PageSearchResult",
+    "PageSource",
+    "PageSummary",
+    "Source",
+    "SourceFolder",
+    "SourceTree",
+    "Topic",
+    "TopicSummary",
+    "Upload",
+    "UploadFilePlan",
+    "UploadPlan",
+    "UploadResult",
+    "UploadTarget",
+    "Wiki",
+    "Workspace",
+    "WorkspaceInvitation",
+    "WorkspaceMember",
+    "WorkspaceMembers",
+]

almanac_contracts-0.5.0/src/almanac_contracts/hosted/api_keys.py

@@ -0,0 +1,18 @@
+from pydantic import Field
+
+from almanac_contracts.models import AlmanacModel
+
+
+class ApiKey(AlmanacModel):
+    api_key_id: str
+    name: str
+    obfuscated_value: str
+    permissions: list[str] = Field(default_factory=list)
+    created_at: str
+    updated_at: str
+    last_used_at: str | None = None
+    expires_at: str | None = None
+
+
+class CreatedApiKey(ApiKey):
+    value: str

almanac_contracts-0.5.0/src/almanac_contracts/hosted/billing.py

@@ -0,0 +1,71 @@
+from typing import Literal
+
+from pydantic import Field
+
+from almanac_contracts.models import AlmanacModel
+
+
+class PlanFeature(AlmanacModel):
+    feature_id: str
+    included: float | None = None
+
+
+class BillingUsage(AlmanacModel):
+    feature_id: str
+    granted: float
+    remaining: float
+    usage: float
+    unlimited: bool = False
+    overage_allowed: bool = False
+    next_reset_at: float | None = None
+
+
+class BillingPlan(AlmanacModel):
+    plan_id: str
+    name: str
+    group: str | None = None
+    price: float | None = None
+    interval: str | None = None
+    action: (
+        Literal["activate", "upgrade", "downgrade", "purchase", "none"] | None
+    ) = None
+    status: Literal["active", "scheduled"] | None = None
+    features: list[PlanFeature] = Field(default_factory=list)
+
+
+class BillingManage(AlmanacModel):
+    allowed: bool
+    reason: Literal["permission", "not_allowed"]
+
+
+class BillingState(AlmanacModel):
+    workspace_id: str
+    manage: BillingManage
+    plans: list[BillingPlan]
+    usage: list[BillingUsage] = Field(default_factory=list)
+
+
+class BillingPortal(AlmanacModel):
+    url: str
+
+
+class BillingPlanChange(AlmanacModel):
+    redirect_url: str | None = None
+
+
+class BillingPreviewLine(AlmanacModel):
+    name: str
+    description: str | None = None
+    subtotal: float | None = None
+    total: float | None = None
+    quantity: float | None = None
+
+
+class BillingPreview(AlmanacModel):
+    plan_id: str
+    currency: str | None = None
+    subtotal: float | None = None
+    total: float | None = None
+    redirect_to_checkout: bool = False
+    checkout_type: str | None = None
+    line_items: list[BillingPreviewLine] = Field(default_factory=list)

almanac_contracts-0.5.0/src/almanac_contracts/hosted/jobs.py

@@ -0,0 +1,63 @@
+from typing import Literal
+
+from almanac_contracts.hosted.status import (
+    ImportStatus,
+    JobEventLevel,
+    JobKind,
+    JobStatus,
+    JobStatusState,
+)
+from almanac_contracts.models import AlmanacModel
+
+
+class Job(AlmanacModel):
+    job_id: str
+    wiki_id: str
+    kind: JobKind
+    status: JobStatus
+    title: str | None
+    current_step: str | None
+    summary: str | None
+    error: str | None
+    status_state: JobStatusState
+    status_label: str
+    created_at: str
+    updated_at: str
+    started_at: str | None
+    finished_at: str | None
+
+
+class JobEvent(AlmanacModel):
+    event_id: str
+    job_id: str
+    sequence: int
+    level: JobEventLevel
+    message: str
+    created_at: str
+    payload_json: dict[str, object] | None = None
+
+
+class JobImportOutcome(AlmanacModel):
+    original_path: str
+    status: ImportStatus
+    source_path: str | None
+    error: str | None
+
+
+class JobSourceChange(AlmanacModel):
+    action: Literal["added", "moved"]
+    path: str
+    previous_path: str | None
+
+
+class JobPageChange(AlmanacModel):
+    action: Literal["created", "updated", "removed"]
+    path: str
+    title: str
+
+
+class JobOutcome(AlmanacModel):
+    job: Job
+    imports: list[JobImportOutcome]
+    sources: list[JobSourceChange]
+    pages: list[JobPageChange]

almanac_contracts-0.5.0/src/almanac_contracts/hosted/pages.py

@@ -0,0 +1,43 @@
+from almanac_contracts.hosted.status import PageStatus, StatusState
+from almanac_contracts.models import AlmanacModel
+
+
+class PageRecord(AlmanacModel):
+    page_id: str
+    wiki_id: str
+    path: str
+    title: str
+    status: PageStatus
+    updated_at: str
+
+
+class PageSummary(PageRecord):
+    folder: str
+    name: str
+    status_state: StatusState
+    status_label: str
+
+
+class PageSearchResult(PageSummary):
+    summary: str
+    rank: float
+    excerpt: str
+
+
+class Page(PageSummary):
+    file_path: str
+    summary: str
+    body_md: str
+    frontmatter_json: dict[str, object]
+
+
+class PageSource(AlmanacModel):
+    page_id: str
+    source_id: str
+    key: str
+    title: str
+    job_id: str | None
+    note: str
+    path: str
+    original_filename: str
+    created_at: str

almanac_contracts-0.5.0/src/almanac_contracts/hosted/sources.py

@@ -0,0 +1,82 @@
+from almanac_contracts.hosted.jobs import Job
+from almanac_contracts.hosted.status import ImportStatus, StatusState, UploadStatus
+from almanac_contracts.models import AlmanacModel
+
+
+class Source(AlmanacModel):
+    source_id: str
+    wiki_id: str
+    path: str
+    folder: str
+    name: str
+    original_filename: str
+    mime_type: str | None
+    size_bytes: int
+    sha256: str
+    created_at: str
+    updated_at: str
+
+
+class Upload(AlmanacModel):
+    upload_id: str
+    wiki_id: str
+    status: UploadStatus
+    status_state: StatusState
+    status_label: str
+    source_count: int
+    summary: str | None
+    error: str | None
+    created_at: str
+    updated_at: str
+    finished_at: str | None
+
+
+class ImportItem(AlmanacModel):
+    import_id: str
+    original_path: str
+    name: str
+    status: ImportStatus
+    status_state: StatusState
+    status_label: str
+    source_id: str | None
+    duplicate_source_id: str | None
+    error: str | None
+    mime_type: str | None
+    size_bytes: int
+    sha256: str
+
+
+class SourceFolder(AlmanacModel):
+    path: str
+    name: str
+    parent: str | None
+    source_count: int
+
+
+class SourceTree(AlmanacModel):
+    folders: list[SourceFolder]
+    sources: list[Source]
+
+
+class UploadResult(AlmanacModel):
+    upload: Upload
+    imports: list[ImportItem]
+    job: Job | None
+
+
+class UploadTarget(AlmanacModel):
+    method: str
+    url: str
+    headers: dict[str, str]
+    expires_at: str
+
+
+class UploadFilePlan(AlmanacModel):
+    file_id: str
+    path: str
+    target: UploadTarget | None
+
+
+class UploadPlan(AlmanacModel):
+    upload: Upload
+    files: list[UploadFilePlan]

almanac_contracts-0.5.0/src/almanac_contracts/hosted/status.py

@@ -0,0 +1,10 @@
+from typing import Literal
+
+JobKind = Literal["ingest", "garden"]
+JobStatus = Literal["queued", "running", "succeeded", "failed"]
+JobEventLevel = Literal["info", "warning", "error"]
+ImportStatus = Literal["pending", "organized", "duplicate", "failed"]
+PageStatus = Literal["active", "archived"]
+UploadStatus = Literal["uploading", "queued", "completed", "failed"]
+StatusState = Literal["ready", "running", "failed", "unknown"]
+JobStatusState = Literal["queued", "running", "succeeded", "failed", "unknown"]

almanac_contracts-0.5.0/src/almanac_contracts/hosted/topics.py

@@ -0,0 +1,12 @@
+from almanac_contracts.hosted.pages import PageRecord
+from almanac_contracts.models import AlmanacModel
+
+
+class TopicSummary(AlmanacModel):
+    topic: str
+    page_count: int
+
+
+class Topic(AlmanacModel):
+    topic: str
+    pages: list[PageRecord]

almanac_contracts-0.5.0/src/almanac_contracts/hosted/wikis.py

@@ -0,0 +1,9 @@
+from almanac_contracts.models import AlmanacModel
+
+
+class Wiki(AlmanacModel):
+    wiki_id: str
+    workspace_id: str
+    slug: str
+    title: str
+    description: str = ""

almanac_contracts-0.5.0/src/almanac_contracts/hosted/workspaces.py

@@ -0,0 +1,63 @@
+from pydantic import Field
+
+from almanac_contracts.models import AlmanacModel
+
+
+class Workspace(AlmanacModel):
+    workspace_id: str
+    name: str
+    slug: str
+    role: str
+    permissions: list[str] = Field(default_factory=list)
+
+
+class WorkspaceAccess(AlmanacModel):
+    workspace_id: str
+    role: str
+    can_manage_members: bool = False
+    can_manage_billing: bool = False
+    can_manage_developers: bool = False
+
+
+class WorkspaceMember(AlmanacModel):
+    membership_id: str
+    user_id: str
+    email: str
+    display_name: str
+    avatar_url: str = ""
+    role: str
+    status: str = "active"
+
+
+class WorkspaceInvitation(AlmanacModel):
+    invitation_id: str
+    email: str
+    role: str
+    state: str = "pending"
+    expires_at: str | None = None
+    created_at: str | None = None
+
+
+class WorkspaceRole(AlmanacModel):
+    slug: str
+    name: str
+    description: str = ""
+
+
+class WorkspaceSeats(AlmanacModel):
+    active: int
+    pending: int = 0
+    used: int
+    granted: float | None = None
+    unlimited: bool = False
+    overage_allowed: bool = False
+    blocked: bool = False
+
+
+class WorkspaceMembers(AlmanacModel):
+    workspace_id: str
+    viewer: WorkspaceAccess
+    members: list[WorkspaceMember] = Field(default_factory=list)
+    invitations: list[WorkspaceInvitation] = Field(default_factory=list)
+    roles: list[WorkspaceRole] = Field(default_factory=list)
+    seats: WorkspaceSeats

almanac_contracts-0.5.0/src/almanac_contracts/models.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AlmanacModel(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class PageCursor(AlmanacModel):
+    limit: int = Field(default=50, ge=1, le=500)
+    offset: int = Field(default=0, ge=0)

almanac_contracts-0.5.0/src/almanac_contracts/urls.py

@@ -0,0 +1,16 @@
+import re
+
+from almanac_contracts.errors import ValidationFailed
+
+HOSTNAME = re.compile(
+    r"(?=.{1,253}\Z)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*"
+    r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?",
+    re.IGNORECASE,
+)
+
+
+def required_hostname(value: str, name: str) -> str:
+    hostname = value.strip()
+    if not HOSTNAME.fullmatch(hostname):
+        raise ValidationFailed(f"{name} must be a hostname")
+    return hostname.lower()

almanac_contracts-0.5.0/src/almanac_contracts.egg-info/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: almanac-contracts
+Version: 0.5.0
+Summary: Shared wire contracts for Almanac clients and services.
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.8

almanac_contracts-0.5.0/src/almanac_contracts.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+pyproject.toml
+src/almanac_contracts/__init__.py
+src/almanac_contracts/errors.py
+src/almanac_contracts/models.py
+src/almanac_contracts/urls.py
+src/almanac_contracts.egg-info/PKG-INFO
+src/almanac_contracts.egg-info/SOURCES.txt
+src/almanac_contracts.egg-info/dependency_links.txt
+src/almanac_contracts.egg-info/requires.txt
+src/almanac_contracts.egg-info/top_level.txt
+src/almanac_contracts/hosted/__init__.py
+src/almanac_contracts/hosted/api_keys.py
+src/almanac_contracts/hosted/billing.py
+src/almanac_contracts/hosted/jobs.py
+src/almanac_contracts/hosted/pages.py
+src/almanac_contracts/hosted/sources.py
+src/almanac_contracts/hosted/status.py
+src/almanac_contracts/hosted/topics.py
+src/almanac_contracts/hosted/wikis.py
+src/almanac_contracts/hosted/workspaces.py

almanac_contracts-0.5.0/src/almanac_contracts.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

almanac_contracts-0.5.0/src/almanac_contracts.egg-info/requires.txt

@@ -0,0 +1 @@
+pydantic>=2.8

almanac_contracts-0.5.0/src/almanac_contracts.egg-info/top_level.txt

@@ -0,0 +1 @@
+almanac_contracts