@voxgig/sdkgen 1.2.1 → 1.3.2

package/dist/cmp/License.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.License = void 0;
+const jostraca_1 = require("jostraca");
+const packageMeta_1 = require("../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 = (0, jostraca_1.cmp)(function License(props) {
+    const { ctx$ } = props;
+    const { model } = ctx$;
+    const year = (model.const && model.const.year) || new Date().getFullYear();
+    (0, jostraca_1.File)({ name: 'LICENSE' }, () => {
+        (0, jostraca_1.Content)(`MIT License
+
+Copyright (c) ${year} ${packageMeta_1.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.
+
+---
+
+${(0, packageMeta_1.nonAffiliation)(model)}
+`);
+    });
+});
+exports.License = License;
+//# sourceMappingURL=License.js.map

package/dist/cmp/License.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"License.js","sourceRoot":"","sources":["../../src/cmp/License.ts"],"names":[],"mappings":";;;AAAA,uCAA6C;AAE7C,wDAAkE;AAGlE,2EAA2E;AAC3E,yEAAyE;AACzE,8EAA8E;AAC9E,kDAAkD;AAClD,MAAM,OAAO,GAAG,IAAA,cAAG,EAAC,SAAS,OAAO,CAAC,KAAU;IAC7C,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAA;IACtB,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IAEtB,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAE1E,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE;QAC7B,IAAA,kBAAO,EAAC;;gBAEI,IAAI,IAAI,uBAAS;;;;;;;;;;;;;;;;;;;;;;EAsB/B,IAAA,4BAAc,EAAC,KAAK,CAAC;CACtB,CAAC,CAAA;IACA,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAIA,0BAAO"}

package/dist/cmp/Readme.js

@@ -5,6 +5,7 @@ const jostraca_1 = require("jostraca");
 const ReadmeIntro_1 = require("./ReadmeIntro");
 const ReadmeInstall_1 = require("./ReadmeInstall");
 const ReadmeQuick_1 = require("./ReadmeQuick");
+const ReadmeErrors_1 = require("./ReadmeErrors");
 const ReadmeModel_1 = require("./ReadmeModel");
 const ReadmeOptions_1 = require("./ReadmeOptions");
 const ReadmeEntity_1 = require("./ReadmeEntity");
@@ -18,6 +19,7 @@ const Readme = (0, jostraca_1.cmp)(function Readme(props) {
         (0, ReadmeIntro_1.ReadmeIntro)({ target });
         (0, ReadmeInstall_1.ReadmeInstall)({ target });
         (0, ReadmeQuick_1.ReadmeQuick)({ target });
+        (0, ReadmeErrors_1.ReadmeErrors)({ target });
         (0, ReadmeHowto_1.ReadmeHowto)({ target });
         (0, ReadmeModel_1.ReadmeModel)({ target });
         (0, ReadmeOptions_1.ReadmeOptions)({ target });

package/dist/cmp/Readme.js.map

@@ -1 +1 @@
-{"version":3,"file":"Readme.js","sourceRoot":"","sources":["../../src/cmp/Readme.ts"],"names":[],"mappings":";;;AACA,uCAA6C;AAG7C,+CAA2C;AAC3C,mDAA+C;AAC/C,+CAA2C;AAC3C,+CAA2C;AAC3C,mDAA+C;AAC/C,iDAA6C;AAC7C,+CAA2C;AAC3C,2DAAuD;AACvD,2CAAuC;AAGvC,MAAM,MAAM,GAAG,IAAA,cAAG,EAAC,SAAS,MAAM,CAAC,KAAU;IAC3C,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAA;IACxB,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,IAAI,CAAA;IAE5B,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE;QAE/B,IAAA,yBAAW,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvB,IAAA,6BAAa,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACzB,IAAA,yBAAW,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvB,IAAA,yBAAW,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvB,IAAA,yBAAW,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvB,IAAA,6BAAa,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACzB,IAAA,2BAAY,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACxB,IAAA,qCAAiB,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QAE7B,IAAA,kBAAO,EAAC;;;;;;CAMX,CAAC,CAAA;IACA,CAAC,CAAC,CAAA;IAEF,4CAA4C;IAC5C,IAAA,qBAAS,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;AACvB,CAAC,CAAC,CAAA;AAIA,wBAAM"}
+{"version":3,"file":"Readme.js","sourceRoot":"","sources":["../../src/cmp/Readme.ts"],"names":[],"mappings":";;;AACA,uCAA6C;AAG7C,+CAA2C;AAC3C,mDAA+C;AAC/C,+CAA2C;AAC3C,iDAA6C;AAC7C,+CAA2C;AAC3C,mDAA+C;AAC/C,iDAA6C;AAC7C,+CAA2C;AAC3C,2DAAuD;AACvD,2CAAuC;AAGvC,MAAM,MAAM,GAAG,IAAA,cAAG,EAAC,SAAS,MAAM,CAAC,KAAU;IAC3C,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAA;IACxB,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,IAAI,CAAA;IAE5B,IAAA,eAAI,EAAC,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE;QAE/B,IAAA,yBAAW,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvB,IAAA,6BAAa,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACzB,IAAA,yBAAW,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvB,IAAA,2BAAY,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACxB,IAAA,yBAAW,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvB,IAAA,yBAAW,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvB,IAAA,6BAAa,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACzB,IAAA,2BAAY,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACxB,IAAA,qCAAiB,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QAE7B,IAAA,kBAAO,EAAC;;;;;;CAMX,CAAC,CAAA;IACA,CAAC,CAAC,CAAA;IAEF,4CAA4C;IAC5C,IAAA,qBAAS,EAAC,EAAE,MAAM,EAAE,CAAC,CAAA;AACvB,CAAC,CAAC,CAAA;AAIA,wBAAM"}

package/dist/cmp/ReadmeErrors.d.ts

@@ -0,0 +1,2 @@
+declare const ReadmeErrors: import("jostraca").Component;
+export { ReadmeErrors };

package/dist/cmp/ReadmeErrors.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadmeErrors = void 0;
+const jostraca_1 = require("jostraca");
+const types_1 = require("../types");
+const opShape_1 = require("../helpers/opShape");
+const opExample_1 = require("../helpers/opExample");
+const naming_1 = require("../helpers/naming");
+const DEFAULT_LANG = {
+    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 = {
+    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 = (0, jostraca_1.cmp)(function ReadmeErrors(props) {
+    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 = (0, types_1.getModelPath)(model, `main.${types_1.KIT}.entity`, { only_active: false, required: false });
+    const ex = Object.values(entity || {}).find((e) => e && e.active !== false);
+    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 = (0, naming_1.safeVarName)(eName.toLowerCase(), target.name);
+    // The entity's id-like key field name, or null when it has none.
+    const idF = (0, opShape_1.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 = (0, opShape_1.entityPrimaryOp)(ex) || 'load';
+    const call = (0, opExample_1.primaryOpCall)(target.name, eName, eLower, primaryOp, idF, ex);
+    (0, jostraca_1.Content)(`
+## Error handling
+
+`);
+    (0, jostraca_1.Content)(lang.entity(call, primaryOp));
+    (0, jostraca_1.Content)(lang.direct);
+});
+exports.ReadmeErrors = ReadmeErrors;
+//# sourceMappingURL=ReadmeErrors.js.map

package/dist/cmp/ReadmeErrors.js.map

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