ourseams-sdk 0.1.0__tar.gz

ourseams_sdk-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+.venv
+.gstack/
+.cursor/
+.claude/
+
+node_modules/
+.pnpm-store/
+dist/
+.turbo/
+.env*
+!.env.example
+!.env*.example
+.next/
+out/
+next-env.d.ts
+
+# the static export of apps/landing; built by `next build`, deployed by wrangler
+out/
+*.tsbuildinfo
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

ourseams_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ourseams_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: ourseams-sdk
+Version: 0.1.0
+Summary: The typed Python client for the seams control plane, generated from its OpenAPI document.
+Project-URL: Homepage, https://ourseams.com
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Description-Content-Type: text/markdown
+
+# seams
+
+The typed Python client for the seams control plane. **Generated from the OpenAPI document**, which is
+emitted from the API's route table — so it cannot describe a shape the API does not serve, and it stays
+in step with `@ourseams/sdk`.
+
+```python
+import os
+from seams import Seams
+
+seams = Seams(api_key=os.environ["SEAMS_SECRET_KEY"])
+
+seams.users.create("alice", models.CreateEndUserRequest(email="alice@firm.com"))
+key = seams.keys.mint(models.MintKeyRequest(end_user_id="alice", bundle="pro"))
+print(key.key)
+```
+
+## One namespace per CLI command group
+
+`operationId` carries the CLI's own verb, so the method reads like the command:
+
+```text
+seams models add smart …        →  seams.models.add("smart", …)
+seams bundles price pro fast …  →  seams.bundles.price("pro", …)
+seams outcomes runs             →  seams.outcomes.runs()
+seams usage --by model          →  seams.usage(by="model")
+```
+
+Top-level commands stay top-level: `usage`, `margin`, `audit`, `doctor`, `capabilities`. Routes the API
+serves but does not offer a client carry `x-seams-internal: true` and get no method.
+
+## Sync and async
+
+`Seams` and `AsyncSeams` are generated from the same document and carry the same 76 methods.
+
+## Two runtime dependencies
+
+`httpx` for the transport and `pydantic` for the models. Field names are Python's — `end_users`, not
+`endUsers` — with the wire name kept as an alias.
+
+## Regenerating
+
+```bash
+uv run python scripts/generate.py   # models and facade
+```
+
+`src/seams/_generated/` is written by the generator. Do not edit it. The document it reads,
+`../openapi.json`, is emitted by [the TypeScript client](../typescript) from the API's route table.

ourseams_sdk-0.1.0/README.md

@@ -0,0 +1,48 @@
+# seams
+
+The typed Python client for the seams control plane. **Generated from the OpenAPI document**, which is
+emitted from the API's route table — so it cannot describe a shape the API does not serve, and it stays
+in step with `@ourseams/sdk`.
+
+```python
+import os
+from seams import Seams
+
+seams = Seams(api_key=os.environ["SEAMS_SECRET_KEY"])
+
+seams.users.create("alice", models.CreateEndUserRequest(email="alice@firm.com"))
+key = seams.keys.mint(models.MintKeyRequest(end_user_id="alice", bundle="pro"))
+print(key.key)
+```
+
+## One namespace per CLI command group
+
+`operationId` carries the CLI's own verb, so the method reads like the command:
+
+```text
+seams models add smart …        →  seams.models.add("smart", …)
+seams bundles price pro fast …  →  seams.bundles.price("pro", …)
+seams outcomes runs             →  seams.outcomes.runs()
+seams usage --by model          →  seams.usage(by="model")
+```
+
+Top-level commands stay top-level: `usage`, `margin`, `audit`, `doctor`, `capabilities`. Routes the API
+serves but does not offer a client carry `x-seams-internal: true` and get no method.
+
+## Sync and async
+
+`Seams` and `AsyncSeams` are generated from the same document and carry the same 76 methods.
+
+## Two runtime dependencies
+
+`httpx` for the transport and `pydantic` for the models. Field names are Python's — `end_users`, not
+`endUsers` — with the wire name kept as an alias.
+
+## Regenerating
+
+```bash
+uv run python scripts/generate.py   # models and facade
+```
+
+`src/seams/_generated/` is written by the generator. Do not edit it. The document it reads,
+`../openapi.json`, is emitted by [the TypeScript client](../typescript) from the API's route table.

ourseams_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "ourseams-sdk"
+version = "0.1.0"
+description = "The typed Python client for the seams control plane, generated from its OpenAPI document."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.27,<1", "pydantic>=2.7,<3"]
+
+[project.urls]
+Homepage = "https://ourseams.com"
+
+[dependency-groups]
+dev = [
+    "datamodel-code-generator>=0.25",
+    "pytest>=8",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pytest-asyncio>=1.4.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/seams"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = ["src/seams/_generated"]
+
+[tool.ruff.lint]
+# typing.Self is 3.11; the floor here is 3.10, and neither client is meant to be subclassed.
+ignore = ["PYI034"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+exclude = "src/seams/_generated"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

ourseams_sdk-0.1.0/scripts/_emit.py

@@ -0,0 +1,73 @@
+"""Emits the facade: one class per CLI command group, sync and async."""
+
+from __future__ import annotations
+
+from _shape import Group, Method, pascal
+
+HEADER = """# generated by scripts/generate.py — do not edit.
+# namespaces and verbs come from operationId, so seams models add reads as models.add().
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+from . import models as _models
+from .._transport import AsyncTransport, Transport
+
+"""
+
+
+def _body(method: Method, prefix: str, wait: str) -> str:
+    if method.result is None:
+        return f'{prefix}self._t.unbuilt("{method.verb}", {method.url})'
+    call = f'self._t.send("{method.verb}", {method.url}, _models.{method.result}{method.extras})'
+    return f"{prefix}{wait}{call}"
+
+
+def _method(method: Method, is_async: bool) -> str:
+    keyword = "async def" if is_async else "def"
+    wait = "await " if is_async else ""
+    hint = "NoReturn" if method.result is None else f"_models.{method.result}"
+    lines = [f"    {keyword} {method.name}(self{method.signature}) -> {hint}:"]
+    if method.summary:
+        lines.append(f'        """{method.summary}"""')
+    lines.append(_body(method, "        return " if method.result else "        ", wait))
+    return "\n".join(lines)
+
+
+def _group(group: Group, is_async: bool) -> str:
+    name = ("Async" if is_async else "") + pascal(group.name)
+    transport = "AsyncTransport" if is_async else "Transport"
+    members = "\n\n".join(_method(method, is_async) for method in group.methods)
+    return (
+        f"class {name}:\n"
+        f"    def __init__(self, transport: {transport}) -> None:\n"
+        f"        self._t = transport\n\n"
+        f"{members}\n"
+    )
+
+
+def _surface(groups: list[Group], loose: list[Method], is_async: bool) -> str:
+    name = ("Async" if is_async else "") + "Surface"
+    transport = "AsyncTransport" if is_async else "Transport"
+    wiring = "\n".join(
+        f"        self.{group.name}: {('Async' if is_async else '') + pascal(group.name)}"
+        f" = {('Async' if is_async else '') + pascal(group.name)}(transport)"
+        for group in groups
+    )
+    members = "\n\n".join(_method(method, is_async) for method in loose)
+    return (
+        f"class {name}:\n"
+        f"    def __init__(self, transport: {transport}) -> None:\n"
+        f"        self._t = transport\n"
+        f"{wiring}\n\n"
+        f"{members}\n"
+    )
+
+
+def render(groups: list[Group], loose: list[Method]) -> str:
+    blocks = [HEADER]
+    for is_async in (False, True):
+        blocks.extend(_group(group, is_async) for group in groups)
+        blocks.append(_surface(groups, loose, is_async))
+    return "\n\n".join(block.rstrip() for block in blocks) + "\n"

ourseams_sdk-0.1.0/scripts/_hints.py

@@ -0,0 +1,54 @@
+"""Renders a generated pydantic field's annotation back into source text."""
+
+from __future__ import annotations
+
+import enum
+import types
+import typing
+from dataclasses import dataclass
+
+SCALARS = {str: "str", int: "int", bool: "bool", float: "float", type(None): "None"}
+
+
+def _name(annotation: object) -> str:
+    if annotation in SCALARS:
+        return SCALARS[annotation]
+    origin = typing.get_origin(annotation)
+    if origin in (list, set, tuple):
+        inner = ", ".join(_name(arg) for arg in typing.get_args(annotation))
+        return f"{origin.__name__}[{inner}]"
+    if origin in (typing.Union, types.UnionType):
+        return " | ".join(_name(arg) for arg in typing.get_args(annotation))
+    if origin is dict:
+        key, value = typing.get_args(annotation)
+        return f"dict[{_name(key)}, {_name(value)}]"
+    if isinstance(annotation, type) and hasattr(annotation, "model_fields"):
+        return f"_models.{annotation.__name__}"
+    if isinstance(annotation, type) and issubclass(annotation, enum.Enum):
+        return f"_models.{annotation.__name__}"
+    return "typing.Any"
+
+
+@dataclass(frozen=True)
+class Argument:
+    name: str
+    hint: str
+    required: bool
+    wire: str
+
+    @property
+    def declaration(self) -> str:
+        if self.required:
+            return f"{self.name}: {self.hint}"
+        # an optional field is already `X | None`; a second one reads as a mistake.
+        hint = self.hint if "None" in self.hint.split(" | ") else f"{self.hint} | None"
+        return f"{self.name}: {hint} = None"
+
+
+def arguments(model: type) -> list[Argument]:
+    found = [
+        Argument(name, _name(field.annotation), field.is_required(), field.alias or name)
+        for name, field in model.model_fields.items()
+    ]
+    # a python signature cannot put a defaulted argument before a required one.
+    return sorted(found, key=lambda argument: not argument.required)

ourseams_sdk-0.1.0/scripts/_resolve.py

@@ -0,0 +1,40 @@
+"""Maps a component schema name to the class the model generator actually emitted for it.
+
+datamodel-code-generator names a class after the first schema it meets with that title, so an
+inline object inside an earlier component can take the name and push the real one to `Usage1`.
+The emitted name then keeps the component name as a prefix — `Usage1`, `ModelModel` — and the
+field set says which of those candidates is the real one.
+"""
+
+from __future__ import annotations
+
+from types import ModuleType
+from typing import Any
+
+
+def _fields(model: type) -> frozenset[str]:
+    return frozenset(field.alias or name for name, field in model.model_fields.items())
+
+
+def resolve(schemas: dict[str, Any], models: ModuleType) -> dict[str, str]:
+    emitted = {
+        name: value
+        for name, value in vars(models).items()
+        if isinstance(value, type) and hasattr(value, "model_fields")
+    }
+    found: dict[str, str] = {}
+    for name, schema in schemas.items():
+        want = frozenset(schema.get("properties", {}))
+        if not want:
+            continue
+        matches = [
+            emitted_name
+            for emitted_name, model in emitted.items()
+            if emitted_name.startswith(name) and _fields(model) == want
+        ]
+        if len(matches) != 1:
+            raise SystemExit(
+                f"cannot resolve schema {name!r} to one generated class: {matches or 'no match'}"
+            )
+        found[name] = matches[0]
+    return found

ourseams_sdk-0.1.0/scripts/_shape.py

@@ -0,0 +1,132 @@
+"""Reads the OpenAPI document into the shape the emitter needs."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from _hints import Argument
+
+# one owner for the document: @ourseams/sdk emits it from the running api, both clients read it.
+DOCUMENT = Path(__file__).resolve().parents[2] / "openapi.json"
+
+
+def snake(name: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower().replace("-", "_")
+
+
+def pascal(name: str) -> str:
+    return "".join(part.capitalize() for part in re.split(r"[-_.]", name))
+
+
+@dataclass(frozen=True)
+class Method:
+    verb: str
+    path: str
+    name: str
+    summary: str
+    result: str | None
+    params: tuple[str, ...]
+    query: tuple[tuple[str, bool], ...]
+    body: str | None
+    fields: tuple[Argument, ...] = ()
+
+    @property
+    def signature(self) -> str:
+        args = [f"{snake(p)}: str" for p in self.params]
+        if self.fields:
+            args.extend(argument.declaration for argument in self.fields)
+        elif self.body is not None:
+            args.append(f"body: _models.{self.body}")
+        args.extend(
+            f"{snake(name)}: str" if required else f"{snake(name)}: str | None = None"
+            for name, required in self.query
+        )
+        return "".join(f", {arg}" for arg in args)
+
+    @property
+    def url(self) -> str:
+        rendered = re.sub(r"\{(\w+)\}", lambda m: f"{{{snake(m.group(1))}}}", self.path)
+        return f'f"{rendered}"' if self.params else f'"{rendered}"'
+
+    @property
+    def extras(self) -> str:
+        parts = []
+        if self.query:
+            pairs = ", ".join(f'"{name}": {snake(name)}' for name, _ in self.query)
+            parts.append(f"query={{{pairs}}}")
+        if self.fields:
+            pairs = ", ".join(f'"{f.wire}": {f.name}' for f in self.fields)
+            parts.append(f"body={{{pairs}}}")
+        elif self.body is not None:
+            parts.append("body=body.model_dump(mode='json', by_alias=True, exclude_none=True)")
+        return "".join(f", {part}" for part in parts)
+
+
+@dataclass
+class Group:
+    name: str
+    methods: list[Method] = field(default_factory=list)
+
+
+def _ref(schema: dict | None) -> str | None:
+    ref = (schema or {}).get("$ref")
+    return ref.rsplit("/", 1)[-1] if ref else None
+
+
+def _json_schema(holder: dict, key: str) -> dict | None:
+    content = holder.get(key, {}).get("content", {})
+    return content.get("application/json", {}).get("schema")
+
+
+def _class(schema: str | None, emitted: dict[str, str] | None) -> str | None:
+    return None if schema is None else (emitted or {}).get(schema, schema)
+
+
+def _keywords(found: tuple[Argument, ...], parameters: list[dict]) -> tuple[Argument, ...]:
+    taken = {snake(p["name"]) for p in parameters if p["in"] in ("path", "query")}
+    return () if any(argument.name in taken for argument in found) else found
+
+
+def read(
+    path: Path = DOCUMENT,
+    fields: dict[str, tuple[Argument, ...]] | None = None,
+    emitted: dict[str, str] | None = None,
+) -> tuple[list[Group], list[Method]]:
+    document = json.loads(path.read_text())
+    groups: dict[str, Group] = {}
+    loose: list[Method] = []
+
+    for url, verbs in document["paths"].items():
+        for verb, operation in verbs.items():
+            identifier = operation.get("operationId")
+            # the mark, the probe and the document are served but not offered, same as @ourseams/sdk.
+            if identifier is None or operation.get("x-seams-internal") is True:
+                continue
+            parameters = operation.get("parameters", [])
+            method = Method(
+                verb=verb.upper(),
+                path=url,
+                name=snake(identifier.split(".")[-1]),
+                summary=operation.get("summary", ""),
+                result=_class(_ref(_json_schema(operation.get("responses", {}), "200")), emitted),
+                params=tuple(p["name"] for p in parameters if p["in"] == "path"),
+                query=tuple(
+                    (p["name"], bool(p.get("required"))) for p in parameters if p["in"] == "query"
+                ),
+                body=(body := _ref(_json_schema(operation, "requestBody"))),
+                fields=_keywords((fields or {}).get(body or "", ()), parameters),
+            )
+            if "." not in identifier:
+                loose.append(method)
+            else:
+                group = identifier.split(".")[0]
+                groups.setdefault(group, Group(group)).methods.append(method)
+
+    for group in groups.values():
+        group.methods.sort(key=lambda m: m.name)
+    return [groups[name] for name in sorted(groups)], sorted(loose, key=lambda m: m.name)

ourseams_sdk-0.1.0/scripts/generate.py

@@ -0,0 +1,73 @@
+"""Regenerates the models and the facade from the OpenAPI document."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+import sys
+from pathlib import Path
+from types import ModuleType
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from _emit import render
+from _hints import arguments
+from _resolve import resolve
+from _shape import DOCUMENT, read
+
+PACKAGE = Path(__file__).resolve().parents[1] / "src" / "seams"
+
+
+def _load(path: Path) -> ModuleType:
+    spec = importlib.util.spec_from_file_location("_seams_models", path)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["_seams_models"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def main() -> None:
+    subprocess.run(
+        [
+            "datamodel-codegen",
+            "--input",
+            str(DOCUMENT),
+            "--input-file-type",
+            "openapi",
+            "--output",
+            str(PACKAGE / "_generated" / "models.py"),
+            "--output-model-type",
+            "pydantic_v2.BaseModel",
+            "--target-python-version",
+            "3.10",
+            "--snake-case-field",
+            # a timestamp in the header makes every regeneration a diff, so the drift check cannot hold.
+            "--disable-timestamp",
+            "--custom-file-header",
+            "# generated by scripts/generate.py from packages/sdk/openapi.json — do not edit.",
+            # the client returns what the api sent: pydantic's AnyUrl appends a trailing slash.
+            "--type-mappings",
+            "string+uri=string",
+            "--formatters",
+            "black",
+        ],
+        check=True,
+    )
+    # loaded by path, not by import: `seams` pulls in the facade this run is about to replace.
+    models = _load(PACKAGE / "_generated" / "models.py")
+
+    document = json.loads(DOCUMENT.read_text())
+    emitted = resolve(document.get("components", {}).get("schemas", {}), models)
+    fields = {schema: tuple(arguments(getattr(models, cls))) for schema, cls in emitted.items()}
+    groups, loose = read(fields=fields, emitted=emitted)
+    (PACKAGE / "_generated" / "client.py").write_text(render(groups, loose))
+    subprocess.run(["ruff", "format", str(PACKAGE / "_generated")], check=True)
+    print(
+        f"generated {len(groups)} namespaces, {sum(len(g.methods) for g in groups) + len(loose)} methods"
+    )
+
+
+if __name__ == "__main__":
+    main()

ourseams_sdk-0.1.0/src/seams/__init__.py

@@ -0,0 +1,55 @@
+"""The seams control plane, one namespace per CLI command group."""
+
+from __future__ import annotations
+
+import httpx
+
+from ._generated import models
+from ._generated.client import AsyncSurface, Surface
+from ._transport import DEFAULT_BASE_URL, AsyncTransport, SeamsError, Transport
+
+__all__ = ["AsyncSeams", "Seams", "SeamsError", "models"]
+
+
+class Seams(Surface):
+    """
+    >>> seams = Seams(api_key=os.environ["SEAMS_SECRET_KEY"])
+    >>> seams.users.create("alice", email="alice@firm.com")
+    >>> seams.keys.mint(end_user_id="alice", bundle="pro").key
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(Transport(api_key, base_url, http_client))
+
+    def close(self) -> None:
+        self._t.close()
+
+    def __enter__(self) -> Seams:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncSeams(AsyncSurface):
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(AsyncTransport(api_key, base_url, http_client))
+
+    async def aclose(self) -> None:
+        await self._t.aclose()
+
+    async def __aenter__(self) -> AsyncSeams:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()