@voxgig/sdkgen 1.2.1 → 1.3.2

package/src/cmp/License.ts

@@ -0,0 +1,49 @@
+import { cmp, Content, File } from 'jostraca'
+
+import { PUBLISHER, nonAffiliation } from '../helpers/packageMeta'
+
+
+// Root MIT LICENSE for the generated SDK repo. The copyright holder is the
+// PUBLISHER (Voxgig): this is an unofficial, generated SDK, so it is NOT
+// attributed to the upstream API owner. A non-affiliation note is appended so
+// the license file itself carries the disclosure.
+const License = cmp(function License(props: any) {
+  const { ctx$ } = props
+  const { model } = ctx$
+
+  const year = (model.const && model.const.year) || new Date().getFullYear()
+
+  File({ name: 'LICENSE' }, () => {
+    Content(`MIT License
+
+Copyright (c) ${year} ${PUBLISHER}
+
+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.
+
+---
+
+${nonAffiliation(model)}
+`)
+  })
+})
+
+
+export {
+  License
+}

package/src/cmp/Readme.ts

@@ -5,6 +5,7 @@ import { cmp, File, Content } from 'jostraca'
 import { ReadmeIntro } from './ReadmeIntro'
 import { ReadmeInstall } from './ReadmeInstall'
 import { ReadmeQuick } from './ReadmeQuick'
+import { ReadmeErrors } from './ReadmeErrors'
 import { ReadmeModel } from './ReadmeModel'
 import { ReadmeOptions } from './ReadmeOptions'
 import { ReadmeEntity } from './ReadmeEntity'
@@ -22,6 +23,7 @@ const Readme = cmp(function Readme(props: any) {
     ReadmeIntro({ target })
     ReadmeInstall({ target })
     ReadmeQuick({ target })
+    ReadmeErrors({ target })
     ReadmeHowto({ target })
     ReadmeModel({ target })
     ReadmeOptions({ target })

package/src/cmp/ReadmeErrors.ts

@@ -0,0 +1,257 @@
+
+import { cmp, Content } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
+import { entityIdField, entityPrimaryOp } from '../helpers/opShape'
+import { primaryOpCall } from '../helpers/opExample'
+import type { ExampleLang, PrimaryCall } from '../helpers/opExample'
+import { safeVarName } from '../helpers/naming'
+
+
+// Error handling is one of the everyday developer tasks, so it gets its
+// own user-facing section rather than being buried in the pipeline
+// explanation. The convention differs by language in two ways:
+//
+//   1. Entity operations (load/list/create/update/remove) either THROW
+//      (ts, js, py, php, rb) or return an error value (go, lua).
+//   2. The low-level `direct()`/`prepare()` escape hatch does NOT always
+//      follow the entity-op convention. In go/lua it returns (value, err);
+//      in ts/js it returns the value or an `Error`; in py/php/rb it returns
+//      the result envelope — branch on `ok`, and read `err` on failure.
+//
+// The entity-op snippet is rendered from the entity's PRIMARY op (never a
+// hardcoded `load`, which a create-only entity lacks) with a type-correct
+// match id (a numeric id renders `1`, not "example_id"). Targets not listed
+// here (ts, js) use DEFAULT_LANG.
+type LangErrors = {
+  // prose + snippet for the entity-op convention, given the pre-rendered
+  // primary-op invocation and its op name.
+  entity: (call: PrimaryCall, op: string) => string
+  // prose + snippet for the direct()/prepare() convention
+  direct: string
+}
+
+
+const DEFAULT_LANG: LangErrors = {
+  entity: (call, op) => `Entity operations reject on failure, so wrap them in \`try\` / \`catch\`:
+
+\`\`\`ts
+try {
+  const ${call.resultVar} = await ${call.expr}
+  console.log(${call.resultVar})
+} catch (err) {
+  console.error('${op} failed:', err)
+}
+\`\`\`
+
+`,
+  direct: `The low-level \`direct()\` method does **not** throw — it returns the
+value or an \`Error\`, so check the result before using it:
+
+\`\`\`ts
+const result = await client.direct({
+  path: '/api/resource/{id}',
+  method: 'GET',
+  params: { id: 'example_id' },
+})
+
+if (result instanceof Error) {
+  throw result
+}
+\`\`\`
+
+`,
+}
+
+
+const LANGS: Record<string, LangErrors> = {
+  py: {
+    entity: (call, op) => `Entity operations raise on failure, so wrap them in \`try\` / \`except\`:
+
+\`\`\`python
+try:
+    ${call.resultVar} = ${call.expr}
+    print(${call.resultVar})
+except Exception as err:
+    print(f"${op} failed: {err}")
+\`\`\`
+
+`,
+    direct: `\`direct()\` does **not** raise — it returns the result envelope. Branch
+on \`ok\`; on failure \`status\` holds the HTTP status (for error responses)
+and \`err\` holds a transport error, so read both defensively:
+
+\`\`\`python
+result = client.direct({
+    "path": "/api/resource/{id}",
+    "method": "GET",
+    "params": {"id": "example_id"},
+})
+
+if not result["ok"]:
+    print("request failed:", result.get("status"), result.get("err"))
+\`\`\`
+
+`,
+  },
+
+  php: {
+    entity: (call, op) => `Entity operations throw a \`\\Throwable\` on failure, so wrap them in
+\`try\` / \`catch\`:
+
+\`\`\`php
+try {
+    $${call.resultVar} = ${call.expr};
+} catch (\\Throwable $err) {
+    echo "Error: " . $err->getMessage();
+}
+\`\`\`
+
+`,
+    direct: `\`direct()\` does **not** throw — it returns the result array. Branch on
+\`ok\`; on failure \`status\` holds the HTTP status (for error responses) and
+\`err\` holds a transport error, so read both defensively:
+
+\`\`\`php
+$result = $client->direct([
+    "path" => "/api/resource/{id}",
+    "method" => "GET",
+    "params" => ["id" => "example_id"],
+]);
+
+if (! $result["ok"]) {
+    $err = $result["err"] ?? null;
+    echo "request failed: " . ($err ? $err->getMessage() : "HTTP " . $result["status"]);
+}
+\`\`\`
+
+`,
+  },
+
+  rb: {
+    entity: (call, op) => `Entity operations raise on failure, so rescue them:
+
+\`\`\`ruby
+begin
+  ${call.resultVar} = ${call.expr}
+rescue => err
+  warn "${op} failed: #{err}"
+end
+\`\`\`
+
+`,
+    direct: `\`direct\` does **not** raise — it returns the result hash. Branch on
+\`ok\`; on failure \`status\` holds the HTTP status (for error responses) and
+\`err\` holds a transport error, so read both defensively:
+
+\`\`\`ruby
+result = client.direct({
+  "path" => "/api/resource/{id}",
+  "method" => "GET",
+  "params" => { "id" => "example_id" },
+})
+
+warn "request failed: #{result["err"] || "HTTP #{result["status"]}"}" unless result["ok"]
+\`\`\`
+
+`,
+  },
+
+  lua: {
+    entity: (call, op) => `Entity operations return \`(value, err)\`. Check \`err\` before using
+the value:
+
+\`\`\`lua
+local ${call.resultVar}, err = ${call.expr}
+if err then error(err) end
+\`\`\`
+
+`,
+    direct: `\`direct\` follows the same \`(value, err)\` convention:
+
+\`\`\`lua
+local result, err = client:direct({
+  path = "/api/resource/{id}",
+  method = "GET",
+  params = { id = "example_id" },
+})
+if err then error(err) end
+\`\`\`
+
+`,
+  },
+
+  go: {
+    entity: (call, op) => `Every entity operation returns \`(value, error)\`. Check \`err\` before
+using the value — there is no exception to catch:
+
+\`\`\`go
+${call.resultVar}, err := ${call.expr}
+if err != nil {
+    // handle err
+    return
+}
+_ = ${call.resultVar}
+\`\`\`
+
+`,
+    direct: `\`Direct\` follows the same \`(value, error)\` convention:
+
+\`\`\`go
+result, err := client.Direct(map[string]any{
+    "path":   "/api/resource/{id}",
+    "method": "GET",
+    "params": map[string]any{"id": "example_id"},
+})
+if err != nil {
+    // handle err
+}
+_ = result
+\`\`\`
+
+`,
+  },
+}
+
+
+const ReadmeErrors = cmp(function ReadmeErrors(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  const lang = LANGS[target.name] || DEFAULT_LANG
+
+  // Derive a real example entity from the model (the same way the sibling
+  // Readme components do) so the snippet never references a phantom entity.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
+  const ex = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
+  const eName = ex ? (ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))) : 'Entity'
+  // Sanitise the variable name against the target's reserved words (a `Delete`
+  // entity must not bind `const delete = ...`).
+  const eLower = safeVarName(eName.toLowerCase(), target.name)
+
+  // The entity's id-like key field name, or null when it has none.
+  const idF = entityIdField(ex)
+  // The entity's PRIMARY op — an op it actually exposes (prefer list/load, else
+  // create/update/remove). A create-only entity therefore never shows a
+  // phantom `.load()`.
+  const primaryOp = entityPrimaryOp(ex) || 'load'
+  const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)
+
+  Content(`
+## Error handling
+
+`)
+
+  Content(lang.entity(call, primaryOp))
+
+  Content(lang.direct)
+})
+
+
+export {
+  ReadmeErrors
+}