@voxgig/sdkgen 1.2.0 → 1.3.1

package/project/.sdk/src/cmp/php/TestEntity_php.ts

@@ -278,8 +278,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-        [$${datavar}_result, $err] = $${entvar}->create($${datavar}, null);
-        $this->assertNull($err);
+        $${datavar}_result = $${entvar}->create($${datavar}, null);
         $${datavar} = Helpers::to_map($${datavar}_result);
         $this->assertNotNull($${datavar});
 `)
@@ -324,8 +323,7 @@ const generateList: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-        [$${listvar}_result, $err] = $${entvar}->list($${matchvar}, null);
-        $this->assertNull($err);
+        $${listvar}_result = $${entvar}->list($${matchvar}, null);
         $this->assertIsArray($${listvar}_result);
 `)
 
@@ -413,8 +411,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-        [$${resdatavar}_result, $err] = $${entvar}->update($${datavar}_up, null);
-        $this->assertNull($err);
+        $${resdatavar}_result = $${entvar}->update($${datavar}_up, null);
         $${resdatavar} = Helpers::to_map($${resdatavar}_result);
         $this->assertNotNull($${resdatavar});
 `)
@@ -479,8 +476,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
     Content(`        $${matchvar} = [
             "id" => $${srcdatavar}["id"],
         ];
-        [$${datavar}_loaded, $err] = $${entvar}->load($${matchvar}, null);
-        $this->assertNull($err);
+        $${datavar}_loaded = $${entvar}->load($${matchvar}, null);
         $${datavar}_load_result = Helpers::to_map($${datavar}_loaded);
         $this->assertNotNull($${datavar}_load_result);
         $this->assertEquals($${datavar}_load_result["id"], $${srcdatavar}["id"]);
@@ -488,8 +484,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
   }
   else {
     Content(`        $${matchvar} = [];
-        [$${datavar}_loaded, $err] = $${entvar}->load($${matchvar}, null);
-        $this->assertNull($err);
+        $${datavar}_loaded = $${entvar}->load($${matchvar}, null);
         $this->assertNotNull($${datavar}_loaded);
 `)
   }
@@ -517,8 +512,7 @@ const generateRemove: OpGen = (ctx, step, index) => {
   Content(`        $${matchvar} = [
             "id" => $${srcdatavar}["id"],
         ];
-        [$_, $err] = $${entvar}->remove($${matchvar}, null);
-        $this->assertNull($err);
+        $${entvar}->remove($${matchvar}, null);
 `)
 }
 

package/project/.sdk/src/cmp/php/Test_php.ts

@@ -13,6 +13,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_php'
 import { TestDirect } from './TestDirect_php'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_php'
 
 
 const Test = cmp(function Test(props: any) {
@@ -47,6 +48,9 @@ class ExistsTest extends TestCase
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // README example snippet test (syntax + offline test-mode run).
+    ReadmeExamplesTest({ target })
   })
 })
 

package/project/.sdk/src/cmp/php/fragment/Entity.fragment.php

@@ -55,6 +55,9 @@ class EntityNameEntity
         return new EntityNameEntity($this->_client, $opts);
     }
 
+    /**
+     * @param EntityName|array $args EntityName data (assoc-array) to store.
+     */
     public function data_set($args): void
     {
         if ($args) {
@@ -63,12 +66,18 @@ class EntityNameEntity
         }
     }
 
+    /**
+     * @return EntityName|array The current EntityName data as an assoc-array.
+     */
     public function data_get()
     {
         ($this->_utility->feature_hook)($this->_entctx, "GetData");
         return Struct::clone($this->_data);
     }
 
+    /**
+     * @param array $args Match filter (any subset of EntityName fields).
+     */
     public function match_set($args): void
     {
         if ($args) {
@@ -77,6 +86,9 @@ class EntityNameEntity
         }
     }
 
+    /**
+     * @return array The current match filter (any subset of EntityName fields).
+     */
     public function match_get()
     {
         ($this->_utility->feature_hook)($this->_entctx, "GetMatch");
@@ -93,7 +105,7 @@ class EntityNameEntity
 
     // #RemoveOp
 
-    private function _run_op($ctx, callable $post_done): array
+    private function _run_op($ctx, callable $post_done): mixed
     {
         $utility = $this->_utility;
 

package/project/.sdk/src/cmp/php/fragment/EntityCreateOp.fragment.php

@@ -3,7 +3,16 @@ require_once __DIR__ . '/../core/Helpers.php';
 
 // EJECT-START
 
-    public function create($reqdata, $ctrl = null): array
+    /**
+     * Create a new EntityName.
+     *
+     * @param EntityNameCreateData|array|null $reqdata Body data as an assoc-array;
+     *   a typed EntityNameCreateData names the shape.
+     * @param mixed $ctrl Optional per-call control overrides.
+     * @return EntityName|array The created EntityName as an assoc-array at the
+     *   SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     */
+    public function create(?array $reqdata = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

package/project/.sdk/src/cmp/php/fragment/EntityListOp.fragment.php

@@ -1,6 +1,15 @@
 // EJECT-START
 
-    public function list($reqmatch, $ctrl = null): array
+    /**
+     * List EntityName items matching the given filter.
+     *
+     * @param EntityNameListMatch|array|null $reqmatch Match filter (any subset
+     *   of EntityName fields) as an assoc-array; EntityNameListMatch names the shape.
+     * @param mixed $ctrl Optional per-call control overrides.
+     * @return EntityName[]|array A list of EntityName items as assoc-arrays at
+     *   the SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     */
+    public function list(?array $reqmatch = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

package/project/.sdk/src/cmp/php/fragment/EntityLoadOp.fragment.php

@@ -3,7 +3,16 @@ require_once __DIR__ . '/../core/Helpers.php';
 
 // EJECT-START
 
-    public function load($reqmatch, $ctrl = null): array
+    /**
+     * Load a single EntityName.
+     *
+     * @param EntityNameLoadMatch|array|null $reqmatch Match criteria (id/query
+     *   fields) as an assoc-array; a typed EntityNameLoadMatch names the shape.
+     * @param mixed $ctrl Optional per-call control overrides.
+     * @return EntityName|array The loaded EntityName as an assoc-array at the
+     *   SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     */
+    public function load(?array $reqmatch = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

package/project/.sdk/src/cmp/php/fragment/EntityRemoveOp.fragment.php

@@ -3,7 +3,16 @@ require_once __DIR__ . '/../core/Helpers.php';
 
 // EJECT-START
 
-    public function remove($reqmatch, $ctrl = null): array
+    /**
+     * Remove an EntityName matching the given criteria.
+     *
+     * @param EntityNameRemoveMatch|array|null $reqmatch Match criteria (id/query
+     *   fields) as an assoc-array; EntityNameRemoveMatch names the shape.
+     * @param mixed $ctrl Optional per-call control overrides.
+     * @return EntityName|array The removed EntityName as an assoc-array at the
+     *   SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     */
+    public function remove(?array $reqmatch = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

package/project/.sdk/src/cmp/php/fragment/EntityUpdateOp.fragment.php

@@ -3,7 +3,16 @@ require_once __DIR__ . '/../core/Helpers.php';
 
 // EJECT-START
 
-    public function update($reqdata, $ctrl = null): array
+    /**
+     * Update an existing EntityName.
+     *
+     * @param EntityNameUpdateData|array|null $reqdata Body data as an assoc-array;
+     *   a typed EntityNameUpdateData names the shape.
+     * @param mixed $ctrl Optional per-call control overrides.
+     * @return EntityName|array The updated EntityName as an assoc-array at the
+     *   SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     */
+    public function update(?array $reqdata = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

package/project/.sdk/src/cmp/php/fragment/Main.fragment.php

@@ -103,7 +103,7 @@ class ProjectNameSDK
         return $this->_rootctx;
     }
 
-    public function prepare(array $fetchargs = []): array
+    public function prepare(array $fetchargs = []): mixed
     {
         $utility = $this->_utility;
         $fetchargs = $fetchargs ?? [];
@@ -149,19 +149,27 @@ class ProjectNameSDK
 
         [$_, $err] = ($utility->prepare_auth)($ctx);
         if ($err) {
-            return [null, $err];
+            return ($utility->make_error)($ctx, $err);
         }
 
-        return ($utility->make_fetch_def)($ctx);
+        [$fetchdef, $fd_err] = ($utility->make_fetch_def)($ctx);
+        if ($fd_err) {
+            return ($utility->make_error)($ctx, $fd_err);
+        }
+        return $fetchdef;
     }
 
-    public function direct(array $fetchargs = []): array
+    public function direct(array $fetchargs = []): mixed
     {
         $utility = $this->_utility;
 
-        [$fetchdef, $err] = $this->prepare($fetchargs);
-        if ($err) {
-            return [["ok" => false, "err" => $err], null];
+        // direct() is the raw-HTTP escape hatch: it never throws, it returns
+        // an {ok, err, ...} dict. prepare() now raises on error, so catch it
+        // and surface the failure through the dict instead.
+        try {
+            $fetchdef = $this->prepare($fetchargs);
+        } catch (\Throwable $err) {
+            return ["ok" => false, "err" => $err];
         }
 
         $fetchargs = $fetchargs ?? [];
@@ -176,14 +184,14 @@ class ProjectNameSDK
         [$fetched, $fetch_err] = ($utility->fetcher)($ctx, $url, $fetchdef);
 
         if ($fetch_err) {
-            return [["ok" => false, "err" => $fetch_err], null];
+            return ["ok" => false, "err" => $fetch_err];
         }
 
         if ($fetched === null) {
-            return [[
+            return [
                 "ok" => false,
                 "err" => $ctx->make_error("direct_no_response", "response: undefined"),
-            ], null];
+            ];
         }
 
         if (is_array($fetched)) {
@@ -208,18 +216,18 @@ class ProjectNameSDK
                 }
             }
 
-            return [[
+            return [
                 "ok" => $status >= 200 && $status < 300,
                 "status" => $status,
                 "headers" => Struct::getprop($fetched, "headers"),
                 "data" => $json_data,
-            ], null];
+            ];
         }
 
-        return [[
+        return [
             "ok" => false,
             "err" => $ctx->make_error("direct_invalid", "invalid response type"),
-        ], null];
+        ];
     }
 
     // <[SLOT]>

package/project/.sdk/src/cmp/py/EntityTypes_py.ts

@@ -0,0 +1,184 @@
+
+
+// Typed-model generator (Python target). Port of EntityTypes_ts.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one module, <sdk>_types.py,
+// with a `class <Name>(TypedDict):` per active entity plus a request/match type
+// per active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned into
+// real Python types by the shared sdkgen helper `canonToType` (source of truth:
+// @voxgig/apidef VALID_CANON).
+//
+// TYPE CHOICE: `TypedDict`, not `@dataclass`. The generated ops return/accept
+// plain runtime dicts (data_get/match_get return `vs.clone(self._data)`; ops
+// take/return dicts), so a `@dataclass` annotation is only aspirational — a
+// strict checker at a call site would see dict-vs-dataclass. A TypedDict *is* a
+// dict shape, so annotating these dict-returning/-accepting ops with TypedDict
+// makes the TYPES MATCH the runtime. Runtime behaviour is unchanged.
+//
+// OPTIONAL FIELDS: a `req:false` field/param is a key that MAY be absent, which
+// is exactly TypedDict `total=False` (key optionality), not `Optional[T]` (a
+// None value). To express required AND optional keys on py>=3.8 WITHOUT a
+// typing_extensions dependency (no `NotRequired`), a type with both splits into
+// a required base `class <Name>Required(TypedDict): ...` and a `total=False`
+// subclass `class <Name>(<Name>Required, total=False): ...` that carries the
+// public name and adds the optional keys. Degenerate shapes collapse to a
+// single class (all-required, all-optional, or empty). The all-optional
+// collapse also serves the match-mirror types (the Python analogue of TS
+// `Partial<${Name}>`).
+//
+// Keep the SAME type-name scheme as every other language: <Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch.
+
+import {
+  cmp, each,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'py'
+
+
+// Python keywords that cannot be used as class-syntax TypedDict field names.
+const PY_KEYWORDS = new Set([
+  'False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await', 'break',
+  'class', 'continue', 'def', 'del', 'elif', 'else', 'except', 'finally',
+  'for', 'from', 'global', 'if', 'import', 'in', 'is', 'lambda', 'nonlocal',
+  'not', 'or', 'pass', 'raise', 'return', 'try', 'while', 'with', 'yield',
+])
+
+
+// A name usable as a class-syntax TypedDict key (valid identifier, not a
+// keyword). Non-identifier/keyword field names have no safe class-syntax
+// rendering, so they are skipped (they remain reachable via the runtime dict).
+function pyIdent(name: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !PY_KEYWORDS.has(name)
+}
+
+
+// Emit a TypedDict named `typeName` from a list of {name, type, optional}
+// items (optionality already decided by the caller — the shared partiality
+// policy for op types, or `req` for the entity data type). Required items
+// become required keys; optional items become not-required keys via a
+// `total=False` extension.
+//
+// Shape selection (see file header for the rationale):
+//   both required + optional -> `<typeName>Required` base + `total=False` sub
+//   only required            -> single `class <typeName>(TypedDict):`
+//   only optional            -> single `class <typeName>(TypedDict, total=False):`
+//   no usable keys           -> single `class <typeName>(TypedDict): pass`
+function emitTypedDict(typeName: string, items: any[]): void {
+  const usable = items.filter((it: any) => it && null != it.name && pyIdent(it.name))
+
+  const required = usable.filter((it: any) => !it.optional)
+  const optional = usable.filter((it: any) => it.optional)
+
+  const field = (it: any) => `    ${it.name}: ${canonToType(it.type, LANG)}
+`
+
+  if (0 === usable.length) {
+    Content(`class ${typeName}(TypedDict):
+    pass
+`)
+    return
+  }
+
+  if (0 === required.length) {
+    Content(`class ${typeName}(TypedDict, total=False):
+`)
+    optional.forEach((it: any) => Content(field(it)))
+    return
+  }
+
+  if (0 === optional.length) {
+    Content(`class ${typeName}(TypedDict):
+`)
+    required.forEach((it: any) => Content(field(it)))
+    return
+  }
+
+  Content(`class ${typeName}Required(TypedDict):
+`)
+  required.forEach((it: any) => Content(field(it)))
+  Content(`
+
+class ${typeName}(${typeName}Required, total=False):
+`)
+  optional.forEach((it: any) => Content(field(it)))
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model } = props.ctx$
+  const target = props.target || {}
+  const ext = target.ext || LANG
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  File({ name: model.const.Name.toLowerCase() + '_types.' + ext }, () => {
+
+    Content(`# Typed models for the ${model.const.Name} SDK.
+#
+# GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+# params (op.<name>.points[].args.params[]). Field/param types come from the
+# canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
+# @voxgig/apidef VALID_CANON). Do not edit by hand.
+#
+# These are TypedDicts, not dataclasses: the SDK ops return/accept plain dicts
+# at runtime, and a TypedDict IS a dict shape, so the types match the runtime.
+# Optional (req:false) keys are modelled as TypedDict key-optionality
+# (total=False), split into a required base + total=False subclass when a type
+# has both required and optional keys.
+
+from __future__ import annotations
+
+from typing import TypedDict, Any
+`)
+
+    entityList.forEach((ent: any) => {
+      const Name = ent.Name
+      const fields = (ent.fields ? each(ent.fields) : [])
+        .filter((f: any) => f.active !== false)
+
+      // Entity data model: one key per field, `req:false` -> optional key.
+      Content(`
+
+`)
+      emitTypedDict(Name, fields.map((f: any) => ({
+        name: f.name, type: f.type, optional: false === f.req,
+      })))
+
+      // Per active op: a request/match type. Members and their optionality come
+      // from the shared partiality policy (opRequestShape); this file only
+      // renders them as a TypedDict.
+      const ops = ent.op || {}
+      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        if (null == ops[opname]) {
+          return
+        }
+
+        const typeName = opTypeName(Name, opname)
+        const { items } = opRequestShape(ent, opname)
+
+        Content(`
+
+`)
+        emitTypedDict(typeName, items)
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/py/Entity_py.ts

@@ -9,6 +9,12 @@ import {
 import { EntityOperation } from './EntityOperation_py'
 
 
+// Op -> generated request-type suffix (keep in sync with EntityTypes_py.ts).
+const OP_SUFFIX: Record<string, 'Match' | 'Data'> = {
+  load: 'Match', list: 'Match', remove: 'Match', create: 'Data', update: 'Data',
+}
+
+
 const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
@@ -19,6 +25,22 @@ const Entity = cmp(function Entity(props: any) {
 
   names(entrep, entity.Name, 'EntityName')
 
+  // Import exactly the typed models this entity references: its data type plus
+  // one request type per ACTIVE op (matches what EntityTypes_py.ts emits).
+  const typeNames = [entity.Name]
+  const opnamesAll = Object.keys(entity.op || {})
+  ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+    if (opnamesAll.includes(opname)) {
+      const suffix = OP_SUFFIX[opname] || 'Match'
+      const cap = opname.charAt(0).toUpperCase() + opname.slice(1)
+      typeNames.push(entity.Name + cap + suffix)
+    }
+  })
+  const typesModule = model.const.Name.toLowerCase() + '_types'
+  const typeImport =
+    'from ' + typesModule + ' import (\n    ' +
+    typeNames.join(',\n    ') + ',\n)'
+
   const ff = Path.normalize(__dirname + '/../../../src/cmp/py/fragment/')
 
   // Entity files go to entity/ folder
@@ -44,6 +66,11 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
+          // Literal-marker slot (jostraca's `#Name` tag pattern is hardcoded to
+          // `//` comments, so Python uses a `# #`-prefixed literal like the op
+          // frag slots) — fills in the typed-model import for this entity.
+          '# #TypeImports': typeImport,
+
           '#Entity-Hook': ({ name, indent }: any) =>
             Content({ indent }, `utility.feature_hook(ctx, "${name}")`),
 

package/project/.sdk/src/cmp/py/MainEntity_py.ts

@@ -8,7 +8,8 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { model } = props.ctx$
 
   Content(`
-    def ${entity.Name}(self, data=None):
+    def ${entity.Name}(self, data=None) -> "${entity.Name}Entity":
+        """Entity factory: client.${entity.Name}().list() / client.${entity.Name}().load({"id": ...})."""
         from entity.${entity.name}_entity import ${entity.Name}Entity
         return ${entity.Name}Entity(self, data)
 

package/project/.sdk/src/cmp/py/Main_py.ts

@@ -22,6 +22,7 @@ import { Package } from './Package_py'
 import { Config } from './Config_py'
 import { Gitignore } from './Gitignore_py'
 import { MainEntity } from './MainEntity_py'
+import { EntityTypes } from './EntityTypes_py'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -77,6 +78,35 @@ self._utility.feature_hook(self._rootctx, "${name}")
           MainEntity(entprops)
         })
       })
+
+    // Type-checker-only imports for the entity factory return annotations
+    // (def <Entity>(...) -> "<Entity>Entity"). Guarded by TYPE_CHECKING so
+    // there is no eager runtime import (the factories still import lazily in
+    // their bodies); this lets mypy resolve list()/load() return types on
+    // client.<Entity>() results — e.g. flagging `.data` on a list() result.
+    const entnames = each(entity)
+    if (entnames.length > 0) {
+      Content(`
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+`)
+      each(entity, (ent: any) => {
+        Content(`    from entity.${ent.name}_entity import ${ent.Name}Entity
+`)
+      })
+    }
+  })
+
+  // Generate the typed-model module (<sdk>_types.py) next to the main SDK file.
+  EntityTypes({ target })
+
+  // PEP 561 marker so the inline type hints ship to consumers. Emitted at the
+  // language root (documents intent for the top-level modules) and inside the
+  // entity package (the type-bearing package, included via package-data).
+  File({ name: 'py.typed' }, () => {
+    Content(``)
   })
 
   // Generate config module
@@ -137,6 +167,11 @@ def _make_feature(name):
     File({ name: '__init__.' + target.ext }, () => {
       Content(``)
     })
+    // PEP 561 marker inside the type-bearing package so setuptools package-data
+    // ("*" = ["py.typed"]) bundles it into the wheel.
+    File({ name: 'py.typed' }, () => {
+      Content(``)
+    })
   })
 
   Folder({ name: 'feature' }, () => {

package/project/.sdk/src/cmp/py/Package_py.ts

@@ -4,6 +4,9 @@ import {
   File,
   cmp,
   collectDeps,
+  pkgDescription,
+  keywords,
+  repoInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -24,6 +27,8 @@ const Package = cmp(async function Package(props: any) {
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
   const distName = `${ns}-${pkgBase}`
+  const { repoUrl, issuesUrl } = repoInfo(model)
+  const kw = keywords(model).map((k) => `"${k}"`).join(', ')
 
   File({ name: 'pyproject.toml' }, () => {
     Content(`[build-system]
@@ -33,14 +38,18 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "${distName}"
 version = "0.0.1"
-description = "${model.const.Name} SDK for Python"
+description = "${pkgDescription(model, 'py')}"
+readme = "README.md"
 license = "MIT"
 requires-python = ">=3.8"
+keywords = [${kw}]
 dependencies = [
-    "requests>=2.33",
 `)
 
+    const seen = new Set<string>()
     for (const d of collectDeps(model, target.name, target.deps)) {
+      if (seen.has(d.name)) continue
+      seen.add(d.name)
       const v = d.source === 'target' ? (d.version || '0.0') : d.version
       Content(`    "${d.name}>=${v}",
 `)
@@ -49,12 +58,24 @@ dependencies = [
     Content(`]
 
 [project.urls]
-Homepage = "https://github.com/voxgig/${model.name}-sdk"
+Homepage = "${repoUrl}"
+Repository = "${repoUrl}"
+Issues = "${issuesUrl}"
+
+# Ship the top-level single-file modules (setuptools find only discovers
+# package dirs, never these) so the documented import actually installs.
+# ${model.const.Name.toLowerCase()}_types holds the generated @dataclass models.
+[tool.setuptools]
+py-modules = ["${model.const.Name.toLowerCase()}_sdk", "${model.const.Name.toLowerCase()}_types", "config", "features"]
 
 # Explicit package list — setuptools auto-discovery refuses to pick when
 # multiple top-level dirs (core/entity/feature/utility) are present.
 [tool.setuptools.packages.find]
 include = ["core*", "entity*", "feature*", "utility*"]
+
+# Ship the PEP 561 py.typed marker(s) so the inline type hints reach consumers.
+[tool.setuptools.package-data]
+"*" = ["py.typed"]
 `)
   })
 })