@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/zig/ReadmeRef_zig.ts

@@ -0,0 +1,400 @@
+
+import { cmp, each, Content, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { zigVarName } from './utility_zig'
+
+
+// Canonical type sentinel -> a zig type name for the field/param tables.
+function zigType(type: any): string {
+  const k = canonKey(type)
+  if ('STRING' === k) return '[]const u8'
+  if ('INTEGER' === k) return 'i64'
+  if ('NUMBER' === k) return 'f64'
+  if ('BOOLEAN' === k) return 'bool'
+  if ('ARRAY' === k) return 'Value (array)'
+  if ('OBJECT' === k) return 'Value (object)'
+  return 'Value'
+}
+
+
+// A type-correct zig expression constructing a voxgig struct Value.
+function zigLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
+  if ('BOOLEAN' === k) return 'h.vbool(true)'
+  if ('ARRAY' === k) return 'h.olist()'
+  if ('OBJECT' === k) return 'h.omap()'
+  return `h.vstr("${placeholder}")`
+}
+
+
+const ReadmeRef = cmp(function ReadmeRef(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  const publishedEntities = each(entity).filter((e: any) => e.active !== false)
+
+  const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
+    load: {
+      sig: 'load(reqmatch: Value, ctrl: Value) OpResult',
+      desc: 'Load a single entity matching the given criteria. `.ok` carries the entity data, `.err` the branded error.',
+    },
+    list: {
+      sig: 'list(reqmatch: Value, ctrl: Value) OpResult',
+      desc: 'List entities matching the given criteria. The match is optional — pass `h.vnull()` to list all records. `.ok` is a `Value` array.',
+    },
+    create: {
+      sig: 'create(reqdata: Value, ctrl: Value) OpResult',
+      desc: 'Create a new entity with the given data. `.ok` carries the created entity data.',
+    },
+    update: {
+      sig: 'update(reqdata: Value, ctrl: Value) OpResult',
+      desc: 'Update an existing entity. The data must include the entity id. `.ok` carries the updated entity data.',
+    },
+    remove: {
+      sig: 'remove(reqmatch: Value, ctrl: Value) OpResult',
+      desc: 'Remove the entity matching the given criteria. `.err` on failure.',
+    },
+  }
+
+
+  File({ name: 'REFERENCE.md' }, () => {
+
+    Content(`# ${model.Name} ${target.title} SDK Reference
+
+Complete API reference for the ${model.Name} ${target.title} SDK.
+
+
+## ${model.Name}SDK
+
+### Constructor
+
+`)
+
+    Content(`\`\`\`zig
+const sdk = @import("sdk");
+const h = sdk.h;
+
+const client = sdk.${model.const.Name}SDK.new(options);
+\`\`\`
+
+Create a new SDK client instance. \`options\` is a \`Value\` map
+(\`h.vnull()\` for none).
+
+**Parameters:**
+
+| Key | Value type | Description |
+| --- | --- | --- |
+${isAuthActive(model) ? '| `apikey` | `string` | API key for authentication. |\n' : ''}| \`base\` | \`string\` | Base URL for API requests. |
+| \`prefix\` | \`string\` | URL prefix appended after base. |
+| \`suffix\` | \`string\` | URL suffix appended after path. |
+| \`headers\` | \`map\` | Custom headers for all requests. |
+| \`feature\` | \`map\` | Feature configuration. |
+| \`system\` | \`map\` | System overrides. |
+
+`)
+
+
+    Content(`
+### Static Functions
+
+`)
+
+    Content(`#### \`test_sdk(testopts: Value, sdkopts: Value) *${model.const.Name}SDK\`
+
+Create a test client with mock features active. Both arguments may be
+\`h.vnull()\`.
+
+\`\`\`zig
+const client = sdk.test_sdk(h.vnull(), h.vnull());
+\`\`\`
+
+`)
+
+
+    Content(`
+### Instance Methods
+
+`)
+
+
+    // Entity factory methods
+    publishedEntities.map((ent: any) => {
+      Content(`#### \`${zigVarName(ent.name)}(entopts: Value) *${ent.Name}Entity\`
+
+Create a new \`${ent.Name}Entity\` instance. Pass \`h.vnull()\` for no
+initial options.
+
+`)
+    })
+
+
+    Content(`#### \`options_map() Value\`
+
+Return a deep copy of the current SDK options.
+
+#### \`get_utility() *Utility\`
+
+Return a copy of the SDK utility object.
+
+#### \`direct(fetchargs: Value) Value\`
+
+Make a direct HTTP request to any API endpoint. Returns a result \`Value\`
+map with \`ok\`, \`status\`, \`headers\`, and \`data\` (or \`err\` on failure).
+This escape hatch returns a map even on a non-2xx response — branch on
+\`h.get_bool(result, "ok")\`.
+
+**Parameters (\`fetchargs\` map keys):**
+
+| Key | Value type | Description |
+| --- | --- | --- |
+| \`path\` | \`string\` | URL path with optional \`{param}\` placeholders. |
+| \`method\` | \`string\` | HTTP method (default: \`"GET"\`). |
+| \`params\` | \`map\` | Path parameter values. |
+| \`query\` | \`map\` | Query string parameters. |
+| \`headers\` | \`map\` | Request headers (merged with defaults). |
+| \`body\` | \`any\` | Request body (maps are JSON-serialized). |
+
+#### \`prepare(fetchargs: Value) E!Value\`
+
+Prepare a fetch definition without sending. Returns the fetchdef (use
+\`catch\`/\`try\` to handle the error union).
+
+`)
+
+
+    // Entity reference sections
+    publishedEntities.map((ent: any) => {
+      const opnames = Object.keys(ent.op || {})
+      const fields = ent.fields || []
+      const idF = entityIdField(ent)
+      const eVar = zigVarName(ent.name)
+      const method = zigVarName(ent.name)
+
+      Content(`
+---
+
+## ${ent.Name}Entity
+
+`)
+
+      if (ent.short) {
+        Content(`${ent.short}
+
+`)
+      }
+
+      Content(`\`\`\`zig
+const ${eVar} = client.${method}(h.vnull());
+\`\`\`
+
+`)
+
+
+      // Field schema
+      if (fields.length > 0) {
+        Content(`### Fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+`)
+        each(fields, (field: any) => {
+          const req = field.req ? 'Yes' : 'No'
+          const desc = field.short || ''
+          Content(`| \`${field.name}\` | \`${zigType(field.type)}\` | ${req} | ${desc} |
+`)
+        })
+
+        Content(`
+`)
+
+        // Field operations breakdown
+        const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
+        if (hasFieldOps) {
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
+          Content(`### Field Usage by Operation
+
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
+`)
+          each(fields, (field: any) => {
+            const fops = field.op || {}
+            const cols = opcols.map((op: string) => {
+              const fop = fops[op]
+              if (null == fop) return '-'
+              if (fop.active === false) return '-'
+              return 'Yes'
+            })
+            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+`)
+          })
+
+          Content(`
+`)
+        }
+      }
+
+
+      // Operation details
+      if (opnames.length > 0) {
+        Content(`### Operations
+
+`)
+
+        opnames.map((opname: string) => {
+          const info = OP_SIGNATURES[opname]
+          if (!info) return
+
+          Content(`#### \`${info.sig}\`
+
+${info.desc}
+
+`)
+
+          if ('load' === opname || 'remove' === opname) {
+            const matchItems = opRequestShape(ent, opname).items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const arg = 0 < matchItems.length
+              ? `h.jo(&.{${matchItems.map((it: any) =>
+                `.{ "${it.name}", ${zigLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)} }`).join(', ')}})`
+              : 'h.vnull()'
+            Content(`\`\`\`zig
+switch (client.${method}(h.vnull()).${opname}(${arg}, h.vnull())) {
+    .ok => |result| std.debug.print("{s}\\n", .{h.stringify(result)}),
+    .err => |e| std.debug.print("${opname} failed: {s}\\n", .{e.msg}),
+}
+\`\`\`
+
+`)
+          }
+          else if ('list' === opname) {
+            Content(`\`\`\`zig
+switch (client.${method}(h.vnull()).list(h.vnull(), h.vnull())) {
+    .ok => |results| std.debug.print("{s}\\n", .{h.stringify(results)}),
+    .err => |e| std.debug.print("list failed: {s}\\n", .{e.msg}),
+}
+\`\`\`
+
+`)
+          }
+          else if ('create' === opname) {
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
+            Content(`\`\`\`zig
+switch (client.${method}(h.vnull()).create(h.jo(&.{
+`)
+            createItems.map((it: any) => {
+              Content(`    .{ "${it.name}", ${zigLit(it.type, 'example_' + it.name)} }, // ${zigType(it.type)}
+`)
+            })
+            Content(`}), h.vnull())) {
+    .ok => |result| std.debug.print("{s}\\n", .{h.stringify(result)}),
+    .err => |e| std.debug.print("create failed: {s}\\n", .{e.msg}),
+}
+\`\`\`
+
+`)
+          }
+          else if ('update' === opname) {
+            const updateItems = opRequestShape(ent, 'update').items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updateLines = updateItems.map((it: any) =>
+              `    .{ "${it.name}", ${zigLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)} },\n`).join('')
+            Content(`\`\`\`zig
+switch (client.${method}(h.vnull()).update(h.jo(&.{
+${updateLines}    // Fields to update
+}), h.vnull())) {
+    .ok => |result| std.debug.print("{s}\\n", .{h.stringify(result)}),
+    .err => |e| std.debug.print("update failed: {s}\\n", .{e.msg}),
+}
+\`\`\`
+
+`)
+          }
+        })
+      }
+
+
+      // Common methods
+      Content(`### Common Methods
+
+#### \`data(args: ?Value) Value\`
+
+Get the entity data. Pass a map to set it.
+
+#### \`matchv(args: ?Value) Value\`
+
+Get the entity match criteria. Pass a map to set it.
+
+#### \`stream(action: []const u8, args: Value, callopts: Value) []Value\`
+
+Run an operation through the pipeline and materialise its result items.
+
+#### \`get_name() []const u8\`
+
+Return the entity name.
+
+`)
+    })
+
+
+    // Features section
+    const activeFeatures = each(feature).filter((f: any) => f.active)
+    if (activeFeatures.length > 0) {
+      Content(`
+---
+
+## Features
+
+| Feature | Version | Description |
+| --- | --- | --- |
+`)
+
+      activeFeatures.map((f: any) => {
+        Content(`| \`${f.name}\` | ${f.version || '0.0.1'} | ${f.title || ''} |
+`)
+      })
+
+      Content(`
+
+Features are activated via the \`feature\` option:
+
+`)
+
+      Content(`\`\`\`zig
+const client = sdk.${model.const.Name}SDK.new(h.jo(&.{
+    .{ "feature", h.jo(&.{
+`)
+      activeFeatures.map((f: any) => {
+        Content(`        .{ "${f.name}", h.jo(&.{.{ "active", h.vbool(true) }}) },
+`)
+      })
+      Content(`    }) },
+}));
+\`\`\`
+
+`)
+    }
+
+  })
+})
+
+
+export {
+  ReadmeRef
+}

package/project/.sdk/src/cmp/zig/ReadmeTopHowto_zig.ts

@@ -0,0 +1,24 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**Zig:**
+\`\`\`zig
+const result = client.direct(h.jo(&.{
+    .{ "path", h.vstr("/api/resource/{id}") },
+    .{ "method", h.vstr("GET") },
+    .{ "params", h.jo(&.{.{ "id", h.vstr("example") }}) },
+}));
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

package/project/.sdk/src/cmp/zig/ReadmeTopQuick_zig.ts

@@ -0,0 +1,96 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { zigVarName } from './utility_zig'
+
+
+// A type-correct zig expression constructing a voxgig struct Value for a
+// param. Strings render the quoted placeholder; numeric/boolean/array/object
+// render a typed literal.
+function zigLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
+  if ('BOOLEAN' === k) return 'h.vbool(true)'
+  if ('ARRAY' === k) return 'h.olist()'
+  if ('OBJECT' === k) return 'h.omap()'
+  return `h.vstr("${placeholder}")`
+}
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `sdk.${model.const.Name}SDK.new(h.jo(&.{\n    .{ "apikey", h.vstr(std.posix.getenv("${envName(model)}_APIKEY") orelse "") },\n}))`
+    : `sdk.${model.const.Name}SDK.new(h.vnull())`
+
+  Content(`\`\`\`zig
+const std = @import("std");
+const sdk = @import("sdk");
+const h = sdk.h;
+
+const client = ${ctor};
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const eVar = zigVarName(exampleEntity.name)
+    const method = zigVarName(exampleEntity.name)
+    const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: null when the entity has no id-like field, in which
+    // case the load example takes no match argument.
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`// List all ${eName.toLowerCase()}s (Ok is a Value array, .err on failure)
+switch (client.${method}(h.vnull()).list(h.vnull(), h.vnull())) {
+    .ok => |${eVar}s| std.debug.print("{s}\\n", .{h.stringify(${eVar}s)}),
+    .err => |e| std.debug.print("list failed: {s}\\n", .{e.msg}),
+}
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `h.jo(&.{${loadItems.map((it: any) =>
+          `.{ "${it.name}", ${zigLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)} }`).join(', ')}})`
+        : 'h.vnull()'
+      Content(`
+// Load a specific ${eName.toLowerCase()} (Ok is the record, .err on failure)
+switch (client.${method}(h.vnull()).load(${loadArg}, h.vnull())) {
+    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar})}),
+    .err => |e| std.debug.print("load failed: {s}\\n", .{e.msg}),
+}
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/zig/ReadmeTopTest_zig.ts

@@ -0,0 +1,82 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { zigVarName } from './utility_zig'
+
+
+// A type-correct zig expression constructing a voxgig struct Value.
+function zigLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
+  if ('BOOLEAN' === k) return 'h.vbool(true)'
+  if ('ARRAY' === k) return 'h.olist()'
+  if ('OBJECT' === k) return 'h.omap()'
+  return 'h.vstr("example")'
+}
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+
+  Content(`\`\`\`zig
+const std = @import("std");
+const sdk = @import("sdk");
+const h = sdk.h;
+
+const client = sdk.test_sdk(h.vnull(), h.vnull());
+`)
+
+  if (exampleEntity && primaryOp) {
+    const method = zigVarName(exampleEntity.name)
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = 'h.vnull()'
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's request match.
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      arg = 0 < items.length
+        ? `h.jo(&.{${items.map((it: any) =>
+          `.{ "${it.name}", ${it.name === idF ? 'h.vstr("test01")' : zigLit(it.type)} }`).join(', ')}})`
+        : 'h.vnull()'
+    } else if ('create' === primaryOp || 'update' === primaryOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = required.length ? required : items.slice(0, 3)
+      arg = 0 < chosen.length
+        ? `h.jo(&.{${chosen.map((it: any) => `.{ "${it.name}", ${zigLit(it.type)} }`).join(', ')}})`
+        : 'h.omap()'
+    }
+    const eVar = zigVarName(exampleEntity.name) + ('list' === primaryOp ? 's' : '')
+    Content(`switch (client.${method}(h.vnull()).${primaryOp}(${arg}, h.vnull())) {
+    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar})}),
+    .err => |e| std.debug.print("${primaryOp} failed: {s}\\n", .{e.msg}),
+}
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/zig/TestDirect_zig.ts

@@ -0,0 +1,66 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import { zigVarName } from './utility_zig'
+
+
+// Per-entity direct-call smoke tests. Emits `test "..."` blocks INTO the
+// shared generated_test.zig file (opened by Test_zig) — see TestEntity_zig for
+// why zig keeps every generated test in one file.
+//
+// The go/rust TestDirect generators build a per-entity mock-fetch harness and
+// assert the exact URL/params the entity's op point resolves. Reproducing that
+// path-extraction + mock-transport harness in zig safely requires a build to
+// validate against, so this generator instead exercises the documented
+// `direct()` / `prepare()` escape hatches through the offline test transport
+// and asserts the result shape. `std`, `sdk`, `h`, `Value` and `vnull()` are
+// in scope from the Test_zig header.
+const TestDirect = cmp(function TestDirect(props: any) {
+  const { entity } = props
+
+  const method = zigVarName(entity.name)
+  const ops = entity.op || {}
+
+  // Only entities with a read op participate (mirrors the go/rust gate, which
+  // skips op-less entities).
+  if (!ops.load && !ops.list) {
+    return
+  }
+
+  Content(`
+test "${method}_direct_smoke" {
+    // direct() drives prepare -> transport and always returns a result map
+    // carrying an \`ok\` flag (never an error union), even on a non-2xx or a
+    // prepare failure.
+    const testsdk = sdk.test_sdk(vnull(), vnull());
+    const result = testsdk.direct(h.jo(&.{
+        .{ "path", h.vstr("/${entity.name}/{id}") },
+        .{ "method", h.vstr("GET") },
+        .{ "params", h.jo(&.{.{ "id", h.vstr("direct01") }}) },
+    }));
+    try std.testing.expect(result == .object);
+    try std.testing.expect(h.get_bool(result, "ok") != null);
+}
+
+test "${method}_prepare_smoke" {
+    // prepare() returns the fetch definition (an error union). The generated
+    // fetchdef always carries a url + method.
+    const testsdk = sdk.test_sdk(vnull(), vnull());
+    const fetchdef = testsdk.prepare(h.jo(&.{
+        .{ "path", h.vstr("/${entity.name}/{id}") },
+        .{ "method", h.vstr("GET") },
+        .{ "params", h.jo(&.{.{ "id", h.vstr("direct01") }}) },
+    })) catch {
+        // A prepare error is acceptable here (base may be unset); the surface
+        // exists and is exercised.
+        return;
+    };
+    try std.testing.expect(std.mem.eql(u8, h.get_str(fetchdef, "method") orelse "", "GET"));
+}
+`)
+})
+
+
+export {
+  TestDirect
+}