@voxgig/sdkgen 1.2.0 → 1.3.1

package/dist/helpers/canonType.js

@@ -0,0 +1,74 @@
+"use strict";
+// Canonical type-sentinel -> language primitive type mapper.
+//
+// SOURCE OF TRUTH for the sentinel set: @voxgig/apidef
+//   ~/Projects/voxgig/apidef ts/src/utility.ts  ->  `const VALID_CANON`
+// (around line 908). VALID_CANON maps an OpenAPI type NAME -> a `$SENTINEL`
+// string (e.g. 'string' -> `$STRING`). The model stores those sentinels on
+// every `fields[].type` and op `points[].args.params[].type`.
+//
+// This table maps the SENTINEL the other way -> a concrete primitive type in
+// each target language, so the typed-model generators (EntityTypes_<lang>.ts)
+// can turn the model's field/param sentinels into real language types.
+//
+// Kept as a small duplicate here (rather than importing VALID_CANON) because
+// VALID_CANON is name->sentinel, is not exported from @voxgig/apidef, and would
+// need inverting; a sentinel->type table is what every language generator
+// actually needs. If VALID_CANON gains a new sentinel, add a row below (all
+// languages) and keep the two in sync.
+//
+// KNOWN GAPS (papered over sanely, documented for the port):
+//  - Unknown / missing sentinel  -> the language's "any" (never throws).
+//  - Array element typing is not in the model: $ARRAY maps to an untyped
+//    list/array. `list` ops return T[] via op-kind inference in the op
+//    fragment, NOT via a field sentinel.
+//  - Object/nested field schemas are not in the corpus: $OBJECT maps to the
+//    language's open record/map type.
+//  - No enum/format/nullability beyond the `req` flag.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANON_ANY = exports.CANON_TYPE = void 0;
+exports.canonToType = canonToType;
+exports.canonKey = canonKey;
+// Bare sentinel key (backticks + leading `$` stripped, upper-cased)
+// -> per-language primitive type name.
+//
+// ONLY the `ts` column is exercised + tested today (the reference target).
+// The other columns are a starting scaffold for the per-language port; verify
+// each against that language's idioms before wiring its EntityTypes_<lang>.ts.
+const CANON_TYPE = {
+    STRING: { ts: 'string', js: 'string', py: 'str', php: 'string', rb: 'String', lua: 'string', go: 'string' },
+    INTEGER: { ts: 'number', js: 'number', py: 'int', php: 'int', rb: 'Integer', lua: 'number', go: 'int' },
+    NUMBER: { ts: 'number', js: 'number', py: 'float', php: 'float', rb: 'Float', lua: 'number', go: 'float64' },
+    BOOLEAN: { ts: 'boolean', js: 'boolean', py: 'bool', php: 'bool', rb: 'Boolean', lua: 'boolean', go: 'bool' },
+    NULL: { ts: 'null', js: 'null', py: 'None', php: 'null', rb: 'NilClass', lua: 'nil', go: 'any' },
+    ARRAY: { ts: 'any[]', js: 'Array', py: 'list', php: 'array', rb: 'Array', lua: 'table', go: '[]any' },
+    OBJECT: { ts: 'Record<string, any>', js: 'Object', py: 'dict', php: 'array', rb: 'Hash', lua: 'table', go: 'map[string]any' },
+    ANY: { ts: 'any', js: '*', py: 'Any', php: 'mixed', rb: 'Object', lua: 'any', go: 'any' },
+};
+exports.CANON_TYPE = CANON_TYPE;
+// Per-language fallback for unknown / missing sentinels.
+// js uses JSDoc's `*` (any type); lua uses `any` (LuaLS).
+const CANON_ANY = {
+    ts: 'any', js: '*', py: 'Any', php: 'mixed', rb: 'Object', lua: 'any', go: 'any',
+};
+exports.CANON_ANY = CANON_ANY;
+// Normalize a raw sentinel value to its bare upper-case key:
+// '`$STRING`' / '$STRING' / 'string' -> 'STRING'.
+function canonKey(sentinel) {
+    if (null == sentinel) {
+        return '';
+    }
+    return String(sentinel).replace(/[`$]/g, '').trim().toUpperCase();
+}
+// Map a field/param type sentinel to a target-language primitive type.
+// Unknown or missing sentinel -> that language's "any" (never throws).
+function canonToType(sentinel, lang) {
+    const l = lang;
+    const fallback = CANON_ANY[l] ?? 'any';
+    const row = CANON_TYPE[canonKey(sentinel)];
+    if (null == row) {
+        return fallback;
+    }
+    return row[l] ?? fallback;
+}
+//# sourceMappingURL=canonType.js.map

package/dist/helpers/canonType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonType.js","sourceRoot":"","sources":["../../src/helpers/canonType.ts"],"names":[],"mappings":"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"}

package/dist/helpers/collectDeps.d.ts

@@ -1,9 +1,10 @@
+import type { SdkModel, ModelDep } from '../types';
 type DepEntry = {
     name: string;
     version: string;
     source: 'feature' | 'target';
-    raw: any;
+    raw: ModelDep;
 };
-declare function collectDeps(model: any, targetName: string, targetDeps: any): DepEntry[];
+declare function collectDeps(model: SdkModel, targetName: string, targetDeps: Record<string, ModelDep> | undefined): DepEntry[];
 export type { DepEntry, };
 export { collectDeps, };

package/dist/helpers/collectDeps.js.map

@@ -1 +1 @@
-{"version":3,"file":"collectDeps.js","sourceRoot":"","sources":["../../src/helpers/collectDeps.ts"],"names":[],"mappings":";AAAA,2EAA2E;AAC3E,+EAA+E;AAC/E,yCAAyC;AACzC,EAAE;AACF,yEAAyE;AACzE,wEAAwE;AACxE,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,8EAA8E;AAC9E,yEAAyE;AACzE,8BAA8B;;AAyD5B,kCAAW;AAvDb,uCAA+B;AAC/B,2CAAkD;AASlD,SAAS,WAAW,CAClB,KAAU,EACV,UAAkB,EAClB,UAAe;IAEf,MAAM,GAAG,GAAe,EAAE,CAAA;IAC1B,MAAM,OAAO,GAAG,IAAA,qBAAY,EAAC,KAAK,EAAE,QAAQ,YAAG,UAAU,CAAC,CAAA;IAE1D,IAAA,eAAI,EAAC,OAAO,EAAE,CAAC,CAAM,EAAE,EAAE;QACvB,MAAM,QAAQ,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,CAAA;QACtC,IAAI,CAAC,QAAQ;YAAE,OAAM;QACrB,IAAA,eAAI,EAAC,QAAQ,EAAE,CAAC,GAAQ,EAAE,EAAE;YAC1B,IAAI,GAAG,EAAE,MAAM,EAAE,CAAC;gBAChB,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,MAAM,EAAE,SAAS;oBACjB,GAAG,EAAE,GAAG;iBACT,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,IAAI,UAAU,EAAE,CAAC;QACf,IAAA,eAAI,EAAC,UAAU,EAAE,CAAC,GAAQ,EAAE,EAAE;YAC5B,IAAI,GAAG,EAAE,MAAM,KAAK,KAAK,EAAE,CAAC;gBAC1B,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,MAAM,EAAE,QAAQ;oBAChB,GAAG,EAAE,GAAG;iBACT,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}
+{"version":3,"file":"collectDeps.js","sourceRoot":"","sources":["../../src/helpers/collectDeps.ts"],"names":[],"mappings":";AAAA,2EAA2E;AAC3E,+EAA+E;AAC/E,yCAAyC;AACzC,EAAE;AACF,yEAAyE;AACzE,wEAAwE;AACxE,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,8EAA8E;AAC9E,yEAAyE;AACzE,8BAA8B;;AA2D5B,kCAAW;AAzDb,uCAA+B;AAC/B,2CAAkD;AAWlD,SAAS,WAAW,CAClB,KAAe,EACf,UAAkB,EAClB,UAAgD;IAEhD,MAAM,GAAG,GAAe,EAAE,CAAA;IAC1B,MAAM,OAAO,GAAG,IAAA,qBAAY,EAAC,KAAK,EAAE,QAAQ,YAAG,UAAU,CAAC,CAAA;IAE1D,IAAA,eAAI,EAAC,OAAO,EAAE,CAAC,CAAM,EAAE,EAAE;QACvB,MAAM,QAAQ,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,CAAA;QACtC,IAAI,CAAC,QAAQ;YAAE,OAAM;QACrB,IAAA,eAAI,EAAC,QAAQ,EAAE,CAAC,GAAQ,EAAE,EAAE;YAC1B,IAAI,GAAG,EAAE,MAAM,EAAE,CAAC;gBAChB,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,MAAM,EAAE,SAAS;oBACjB,GAAG,EAAE,GAAG;iBACT,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,IAAI,UAAU,EAAE,CAAC;QACf,IAAA,eAAI,EAAC,UAAU,EAAE,CAAC,GAAQ,EAAE,EAAE;YAC5B,IAAI,GAAG,EAAE,MAAM,KAAK,KAAK,EAAE,CAAC;gBAC1B,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,MAAM,EAAE,QAAQ;oBAChB,GAAG,EAAE,GAAG;iBACT,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/helpers/naming.d.ts

@@ -0,0 +1,3 @@
+declare function isReservedName(name: string, lang: string): boolean;
+declare function safeVarName(name: string, lang: string): string;
+export { isReservedName, safeVarName, };

package/dist/helpers/naming.js

@@ -0,0 +1,51 @@
+"use strict";
+// Reserved-word sanitiser for generated doc-example variable names.
+//
+// A doc example binds a variable named after the lowercased entity name
+// (e.g. `const delete = await client.Delete().load()`). When that name is a
+// reserved word in the target language the snippet does not compile
+// (TS1109/TS1389 for `delete`). `safeVarName` appends `_` to any reserved
+// name so the example still reads clearly and compiles.
+//
+// Only languages whose build/vet actually rejects the name are listed. JS and
+// TS share the ECMAScript reserved set (plus the strict-mode / contextual
+// words a `const` binding trips on). Go lists its 25 keywords — a var named
+// `type`/`func`/`range` fails `go build`; Go builtins like `delete`/`len` are
+// NOT keywords and are legal identifiers, so they are intentionally omitted.
+// py/php/rb/lua rarely collide on a lowercased entity name and are not treated
+// here (add a set if a real collision surfaces).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isReservedName = isReservedName;
+exports.safeVarName = safeVarName;
+const JS_RESERVED = new Set([
+    'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
+    'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
+    'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new',
+    'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try',
+    'typeof', 'var', 'void', 'while', 'with', 'yield',
+    // strict-mode / contextual words that are invalid as a `const`/`let` binding
+    'await', 'implements', 'interface', 'let', 'package', 'private',
+    'protected', 'public', 'static',
+]);
+const GO_RESERVED = new Set([
+    'break', 'case', 'chan', 'const', 'continue', 'default', 'defer', 'else',
+    'fallthrough', 'for', 'func', 'go', 'goto', 'if', 'import', 'interface',
+    'map', 'package', 'range', 'return', 'select', 'struct', 'switch', 'type',
+    'var',
+]);
+const RESERVED = {
+    ts: JS_RESERVED,
+    js: JS_RESERVED,
+    go: GO_RESERVED,
+};
+// Is `name` a reserved word (an illegal identifier) in the target language?
+function isReservedName(name, lang) {
+    const set = RESERVED[lang];
+    return !!set && set.has(name);
+}
+// A collision-free variable name for the target language: the name unchanged
+// unless it is reserved, in which case a trailing `_` is appended.
+function safeVarName(name, lang) {
+    return isReservedName(name, lang) ? name + '_' : name;
+}
+//# sourceMappingURL=naming.js.map

package/dist/helpers/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../../src/helpers/naming.ts"],"names":[],"mappings":";AAAA,oEAAoE;AACpE,EAAE;AACF,wEAAwE;AACxE,4EAA4E;AAC5E,oEAAoE;AACpE,0EAA0E;AAC1E,wDAAwD;AACxD,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,+EAA+E;AAC/E,iDAAiD;;AA0C/C,wCAAc;AACd,kCAAW;AAzCb,MAAM,WAAW,GAAG,IAAI,GAAG,CAAS;IAClC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU;IAClE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO;IACvE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK;IACvE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK;IACnE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO;IACjD,6EAA6E;IAC7E,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS;IAC/D,WAAW,EAAE,QAAQ,EAAE,QAAQ;CAChC,CAAC,CAAA;AAEF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAS;IAClC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;IACxE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW;IACvE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM;IACzE,KAAK;CACN,CAAC,CAAA;AAEF,MAAM,QAAQ,GAAgC;IAC5C,EAAE,EAAE,WAAW;IACf,EAAE,EAAE,WAAW;IACf,EAAE,EAAE,WAAW;CAChB,CAAA;AAGD,4EAA4E;AAC5E,SAAS,cAAc,CAAC,IAAY,EAAE,IAAY;IAChD,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC1B,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC/B,CAAC;AAGD,6EAA6E;AAC7E,mEAAmE;AACnE,SAAS,WAAW,CAAC,IAAY,EAAE,IAAY;IAC7C,OAAO,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAA;AACvD,CAAC"}

package/dist/helpers/opExample.d.ts

@@ -0,0 +1,13 @@
+type ExampleLang = 'ts' | 'js' | 'py' | 'php' | 'rb' | 'lua' | 'go';
+declare function litFor(lang: ExampleLang, type: any): string;
+declare function idLiteral(ent: any, op: string, idF: string | null): string;
+declare function matchArg(lang: ExampleLang, idF: string | null, idLit: string): string;
+declare function dataArg(lang: ExampleLang, ent: any, op: string, idF: string | null): string;
+type PrimaryCall = {
+    expr: string;
+    resultVar: string;
+    isVoid: boolean;
+};
+declare function primaryOpCall(lang: ExampleLang, eName: string, eLower: string, op: string, idF: string | null, ent: any): PrimaryCall;
+export { primaryOpCall, idLiteral, matchArg, dataArg, litFor, };
+export type { ExampleLang, PrimaryCall, };

package/dist/helpers/opExample.js

@@ -0,0 +1,149 @@
+"use strict";
+// Renders a single, type-correct entity-op CALL for the neutral doc
+// components (ReadmeErrors, ReadmeExplanation) that illustrate a convention
+// (throw-on-error, stateful entities) with one representative operation.
+//
+// Two model traps this centralises:
+//   1. OP-AWARENESS — the illustrated op must be one the entity actually
+//      exposes. A create-only entity has no `load` method, so these components
+//      pick the entity's PRIMARY op (entityPrimaryOp) rather than hardcoding
+//      `load`, and this module renders whatever op that is.
+//   2. TYPE-CORRECT MATCH ID — an entity can carry its id ONLY in the
+//      load-match params (no `id` data field). The example id literal is
+//      therefore derived from the OP's param type (opRequestShape), not the
+//      entity fields, so a numeric match id renders `1` and not `"example_id"`
+//      (which would be a TS2322 against a `number` match).
+//
+// Output is the invocation EXPRESSION and its result binding; the surrounding
+// prose / try-catch scaffolding stays in each component's per-language table.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.primaryOpCall = primaryOpCall;
+exports.idLiteral = idLiteral;
+exports.matchArg = matchArg;
+exports.dataArg = dataArg;
+exports.litFor = litFor;
+const canonType_1 = require("./canonType");
+const opShape_1 = require("./opShape");
+function cap(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+// A type-correct literal for a canonical type sentinel, in the target language.
+function litFor(lang, type) {
+    const k = (0, canonType_1.canonKey)(type);
+    if ('INTEGER' === k || 'NUMBER' === k)
+        return '1';
+    if ('BOOLEAN' === k)
+        return 'py' === lang ? 'True' : ('rb' === lang ? 'true' : 'true');
+    if ('ARRAY' === k)
+        return ('lua' === lang) ? '{}' : ('go' === lang ? '[]any{}' : '[]');
+    if ('OBJECT' === k)
+        return ('go' === lang) ? 'map[string]any{}' : '{}';
+    return '"example"';
+}
+// The example id literal for an op's match key, typed from the op's declared
+// param (falling back to the entity field) so a numeric id is never quoted.
+function idLiteral(ent, op, idF) {
+    if (null == idF)
+        return '"example_id"';
+    const item = (0, opShape_1.opRequestShape)(ent, op).items.find((it) => it.name === idF);
+    const k = (0, canonType_1.canonKey)(item && item.type);
+    return ('INTEGER' === k || 'NUMBER' === k) ? '1' : '"example_id"';
+}
+// Render a match object `{ idF: idLit }` (or empty when the entity has no id
+// key) in the target language's object syntax.
+function matchArg(lang, idF, idLit) {
+    if (null == idF)
+        return 'go' === lang ? 'nil' : '';
+    switch (lang) {
+        case 'py': return `{"${idF}": ${idLit}}`;
+        case 'php': return `["${idF}" => ${idLit}]`;
+        case 'rb': return `{ "${idF}" => ${idLit} }`;
+        case 'lua': return `{ ${idF} = ${idLit} }`;
+        case 'go': return `map[string]any{"${idF}": ${idLit}}`;
+        default: return `{ ${idF}: ${idLit} }`;
+    }
+}
+// The entity's required writable fields for a create/update body, rendered as
+// `key: value` pairs (capped) in the target language's object syntax. Ensures
+// the body satisfies a typed CreateData/UpdateData (required fields present).
+function dataArg(lang, ent, op, idF) {
+    const items = (0, opShape_1.opRequestShape)(ent, op).items
+        .filter((it) => it.name !== idF && it.name !== 'id');
+    const required = items.filter((it) => !it.optional);
+    // ALL required fields must appear (a typed CreateData rejects a partial); cap
+    // only the optional fallback used when the op declares no required field.
+    const chosen = required.length ? required : items.slice(0, 3);
+    const pairs = chosen.map((it) => {
+        const v = litFor(lang, it.type);
+        switch (lang) {
+            case 'py': return `"${it.name}": ${v}`;
+            case 'php': return `"${it.name}" => ${v}`;
+            case 'rb': return `"${it.name}" => ${v}`;
+            case 'lua': return `${it.name} = ${v}`;
+            case 'go': return `"${it.name}": ${v}`;
+            default: return `${it.name}: ${v}`;
+        }
+    });
+    switch (lang) {
+        case 'php': return `[${pairs.join(', ')}]`;
+        case 'lua': return `{ ${pairs.join(', ')} }`;
+        case 'go': return `map[string]any{${pairs.join(', ')}}`;
+        default: return `{ ${pairs.join(', ')} }`;
+    }
+}
+// Render the entity's PRIMARY-op invocation in `lang`. `eName` is the
+// Capitalised entity name, `eLower` the variable-safe lowercase name, `op` the
+// primary op name. Method spelling / factory syntax follow each language's
+// idiom (Go PascalCase + ctrl arg, Lua `:` calls, Ruby paren-less factory).
+function primaryOpCall(lang, eName, eLower, op, idF, ent) {
+    const isMatch = 'load' === op || 'remove' === op;
+    const isList = 'list' === op;
+    const isData = 'create' === op || 'update' === op;
+    const idLit = idLiteral(ent, op, idF);
+    // Factory + method spelling per language.
+    const method = 'go' === lang ? cap(op) : op;
+    let factory;
+    let sep;
+    if ('go' === lang) {
+        factory = `client.${eName}(nil)`;
+        sep = '.';
+    }
+    else if ('lua' === lang) {
+        factory = `client:${eName}()`;
+        sep = ':';
+    }
+    else if ('rb' === lang) {
+        factory = `client.${eName}`;
+        sep = '.';
+    }
+    else if ('php' === lang) {
+        factory = `$client->${eName}()`;
+        sep = '->';
+    }
+    else {
+        factory = `client.${eName}()`;
+        sep = '.';
+    }
+    // Argument string per op + language.
+    let arg;
+    if (isList) {
+        arg = 'go' === lang ? 'nil' : '';
+    }
+    else if (isMatch) {
+        arg = matchArg(lang, idF, idLit);
+    }
+    else if (isData) {
+        arg = dataArg(lang, ent, op, idF);
+    }
+    else {
+        arg = 'go' === lang ? 'nil' : '';
+    }
+    // Go passes a trailing ctrl arg on every entity method.
+    if ('go' === lang) {
+        arg = arg + ', nil';
+    }
+    const expr = `${factory}${sep}${method}(${arg})`;
+    const resultVar = isList ? eLower + 's' : eLower;
+    return { expr, resultVar, isVoid: 'remove' === op };
+}
+//# sourceMappingURL=opExample.js.map

package/dist/helpers/opExample.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opExample.js","sourceRoot":"","sources":["../../src/helpers/opExample.ts"],"names":[],"mappings":"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"}

package/dist/helpers/opShape.d.ts

@@ -0,0 +1,18 @@
+declare const OP_SUFFIX: Record<string, 'Match' | 'Data'>;
+declare function opTypeName(Name: string, opname: string): string;
+type OpShapeItem = {
+    name: string;
+    type: any;
+    optional: boolean;
+};
+declare function opParams(op: any): any[];
+declare function opRequestShape(ent: any, opname: string): {
+    items: OpShapeItem[];
+    fromParams: boolean;
+};
+declare function entityIdField(ent: any): string | null;
+declare function entityOps(ent: any): string[];
+declare function entityPrimaryOp(ent: any): string | null;
+declare function entityDataIdField(ent: any): string | null;
+export { OP_SUFFIX, opTypeName, opParams, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, };
+export type { OpShapeItem, };

package/dist/helpers/opShape.js

@@ -0,0 +1,193 @@
+"use strict";
+// Per-op request-payload shape + partiality policy for the typed-model
+// generators (EntityTypes_<lang>.ts).
+//
+// SINGLE SOURCE OF TRUTH for two things every language generator needs:
+//   1. The type-name scheme: <Name>{Load,List,Remove}Match /
+//      <Name>{Create,Update}Data (OP_SUFFIX + opTypeName).
+//   2. Which fields make up an op's request payload, and whether each is
+//      required or optional (opRequestShape) — i.e. the partiality policy.
+//
+// PARTIALITY POLICY
+//   Op-declared params win: if the op declares params
+//   (op.<name>.points[].args.params[]), the payload is built from them and a
+//   param is optional iff `reqd === false` (this is how path/query params such
+//   as {id} become required). `fromParams` is true in that case.
+//
+//   Otherwise the payload mirrors the entity's fields, filtered to those active
+//   for the op (field.op[opname].active !== false; absent -> participates), and
+//   optionality is decided per-op:
+//     create -> required iff `field.req` (server-shaped required fields);
+//     update -> all optional (patch);
+//     load / remove -> a field named `id` is required, the rest optional
+//       (best-effort key convention; degrades to all-optional if no `id`);
+//     list -> all optional (filter).
+//
+// The generators consume `items` (each already carrying its final `optional`
+// flag) and render them in the target language's struct/interface/TypedDict
+// syntax; the policy itself is language-neutral and tested in isolation.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OP_SUFFIX = void 0;
+exports.opTypeName = opTypeName;
+exports.opParams = opParams;
+exports.opRequestShape = opRequestShape;
+exports.entityIdField = entityIdField;
+exports.entityDataIdField = entityDataIdField;
+exports.entityOps = entityOps;
+exports.entityPrimaryOp = entityPrimaryOp;
+const jostraca_1 = require("jostraca");
+// The five ops, and whether their request payload is a `Match` (query/id) or
+// `Data` (body) — this fixes the generated type-name suffix per op.
+const OP_SUFFIX = {
+    load: 'Match',
+    list: 'Match',
+    remove: 'Match',
+    create: 'Data',
+    update: 'Data',
+};
+exports.OP_SUFFIX = OP_SUFFIX;
+function cap(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+// The generated type name for an op's request payload, e.g. AdviceLoadMatch.
+function opTypeName(Name, opname) {
+    return Name + cap(opname) + (OP_SUFFIX[opname] || 'Match');
+}
+// Collect an op's params, deduped by name across all of its points.
+function opParams(op) {
+    const points = op && op.points ? (0, jostraca_1.each)(op.points) : [];
+    const seen = {};
+    const out = [];
+    points.forEach((pt) => {
+        const params = pt && pt.args && pt.args.params ? (0, jostraca_1.each)(pt.args.params) : [];
+        params.forEach((p) => {
+            if (p && null != p.name && !seen[p.name]) {
+                seen[p.name] = true;
+                out.push(p);
+            }
+        });
+    });
+    return out;
+}
+// Does a field participate in an op? Absent op-entry -> participates; only an
+// explicit `active: false` excludes it.
+function fieldInOp(field, opname) {
+    const fop = field && field.op && field.op[opname];
+    return null == fop || fop.active !== false;
+}
+// Decide optionality for a field in a no-params request payload, per op.
+function fieldOptional(field, opname) {
+    switch (opname) {
+        case 'create':
+            // Respect the model's required flag: required unless req === false.
+            return false === field.req;
+        case 'update':
+            // Patch semantics — every field optional.
+            return true;
+        case 'load':
+        case 'remove':
+            // Best-effort key convention: the `id` field is required, rest optional.
+            return 'id' !== field.name;
+        case 'list':
+        default:
+            // Filter — every field optional.
+            return true;
+    }
+}
+// The ordered request-payload members for an entity op, with each member's
+// required/optional decision baked in. `fromParams` records whether the op's
+// declared params were used (true) or the entity-field fallback (false).
+function opRequestShape(ent, opname) {
+    const op = ent && ent.op ? ent.op[opname] : null;
+    if (null == op) {
+        return { items: [], fromParams: false };
+    }
+    const params = opParams(op);
+    if (0 < params.length) {
+        const items = params.map((p) => ({
+            name: p.name,
+            type: p.type,
+            optional: false === p.reqd,
+        }));
+        return { items, fromParams: true };
+    }
+    const fields = (ent.fields ? (0, jostraca_1.each)(ent.fields) : [])
+        .filter((f) => f.active !== false)
+        .filter((f) => fieldInOp(f, opname));
+    const items = fields.map((f) => ({
+        name: f.name,
+        type: f.type,
+        optional: fieldOptional(f, opname),
+    }));
+    return { items, fromParams: false };
+}
+// The entity's id-like key field, or null when it has none. Used by the doc
+// generators to decide whether an example may key a load/remove on `{ id: ... }`
+// and access `.id` on a returned entity, OR must degrade to `load()` with no
+// argument (some APIs model an entity whose load match carries no id — e.g. a
+// response-wrapped spec, where AqiLoadMatch is { code, data, msg }). Prefers the
+// model's declared id field name, then a literal `id`, checking the load-match
+// shape first and the entity's own fields as a fallback.
+function entityIdField(ent) {
+    if (null == ent) {
+        return null;
+    }
+    const idName = (ent.id && ent.id.field) || 'id';
+    const loadItems = opRequestShape(ent, 'load').items;
+    if (loadItems.some((it) => it.name === idName)) {
+        return idName;
+    }
+    if (loadItems.some((it) => it.name === 'id')) {
+        return 'id';
+    }
+    // NO fallback to entity.fields: this is the load-MATCH key. An entity whose
+    // DATA type has an `id` field but whose load match does NOT (a query-param
+    // load, e.g. playstation-store's StoreLoadMatch { age, country, ... }) must
+    // degrade to a no-arg load(); `.id` access is decided by entityDataIdField.
+    return null;
+}
+// The entity's ACTIVE op names, in canonical CRUD order (list, load, create,
+// update, remove), with any non-canonical ops appended in sorted order. Doc
+// generators must gate an op example on this (an op present in the model but
+// `active: false` generates no method, so an example calling it would not
+// compile) — NOT on the raw `Object.keys(ent.op)`, which includes inactive ops.
+const CANON_OP_ORDER = ['list', 'load', 'create', 'update', 'remove'];
+function entityOps(ent) {
+    const ops = (ent && ent.op) || {};
+    const active = Object.keys(ops).filter((o) => ops[o] && ops[o].active !== false);
+    return CANON_OP_ORDER.filter((o) => active.includes(o))
+        .concat(active.filter((o) => !CANON_OP_ORDER.includes(o)).sort());
+}
+// The entity's primary/representative op for a single illustrative call —
+// prefer a read op (list, then load) so the snippet needs no fabricated match,
+// then fall back to create/update/remove. null when the entity exposes no op.
+// Doc generators MUST pick their "primary" op through this rather than
+// hardcoding `load`: a create-only entity has no `load` method.
+function entityPrimaryOp(ent) {
+    const ops = entityOps(ent);
+    for (const o of CANON_OP_ORDER) {
+        if (ops.includes(o)) {
+            return o;
+        }
+    }
+    return ops[0] || null;
+}
+// The id field on the entity's DATA type (its fields[]), or null. DISTINCT from
+// entityIdField (the load-MATCH key): an API can model a load match that carries
+// an `id` param while the response entity itself has no `id` field, so `.id`
+// access on a RETURNED record must be guarded on this, not on the match key.
+function entityDataIdField(ent) {
+    if (null == ent) {
+        return null;
+    }
+    const idName = (ent.id && ent.id.field) || 'id';
+    const fields = ent.fields ? (0, jostraca_1.each)(ent.fields) : [];
+    if (fields.some((f) => f && f.name === idName)) {
+        return idName;
+    }
+    if (fields.some((f) => f && f.name === 'id')) {
+        return 'id';
+    }
+    return null;
+}
+//# sourceMappingURL=opShape.js.map

package/dist/helpers/opShape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opShape.js","sourceRoot":"","sources":["../../src/helpers/opShape.ts"],"names":[],"mappings":"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"}

package/dist/helpers/packageMeta.d.ts

@@ -0,0 +1,27 @@
+declare const PUBLISHER = "Voxgig";
+declare const PUBLISHER_URL = "https://voxgig.com";
+declare const SECURITY_EMAIL = "security@voxgig.com";
+declare const GENERATOR_URL = "https://github.com/voxgig/sdkgen";
+declare const LANG_LABEL: Record<string, string>;
+declare function langLabel(target: string): string;
+declare function repoInfo(model: any): {
+    slug: any;
+    origin: any;
+    repo: string;
+    repoUrl: string;
+    issuesUrl: string;
+    changelogUrl: string;
+    releasesUrl: string;
+};
+declare function registryState(model: any, target: string): 'tag' | 'pending' | 'active' | 'inactive';
+declare function isPublished(model: any, target: string): boolean;
+declare function registryName(model: any, target: string): string;
+declare function vendorCommand(model: any, target: string): string;
+declare function apiName(model: any): string;
+declare function packageName(model: any, eco: string): string;
+declare function installCommand(model: any, target: string): string;
+declare function pkgDescription(model: any, target: string): string;
+declare function nonAffiliation(model: any): string;
+declare function keywords(model: any): string[];
+declare function envName(model: any): string;
+export { PUBLISHER, PUBLISHER_URL, SECURITY_EMAIL, GENERATOR_URL, LANG_LABEL, langLabel, repoInfo, apiName, packageName, installCommand, registryState, isPublished, registryName, vendorCommand, pkgDescription, nonAffiliation, keywords, envName, };