@voxgig/sdkgen 4.19.1 → 4.21.0

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

@@ -0,0 +1,325 @@
+
+import {
+  Content,
+  File,
+  Folder,
+  cmp,
+  isHttpBasicAuth,
+  resolveAuthIn,
+  resolveAuthName,
+  resolveAuthPrefix,
+} from '@voxgig/sdkgen'
+
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
+// rather than templated.
+//
+// This was a static file in `tm/php/utility/` that hardcoded an
+// `authorization` HEADER. apidef has always resolved the scheme's `in` and
+// `name` into `main.kit.info.security` — joplin's says
+// `in: "query", name: "token"` — and generation dropped both. The result
+// was an SDK that sent a header the API does not read and never sent the
+// query parameter it does, so it could not authenticate at all. Four repos
+// in the cedar fleet shipped that way: joplin (`token`), pipedrive
+// (`api_token`), trello (`key`), lm-umbrella (`apiKey`).
+//
+// A template cannot fix this, because the three placements need three
+// different bodies and a template has to pick one. A component emits the
+// branch this API actually uses and nothing else — no dead query code in a
+// bearer-token SDK, and no runtime `if` on a value that is fixed at
+// generation time.
+//
+// The php peer of cmp/ts/PrepareAuth_ts.ts.
+const PrepareAuth = cmp(async function PrepareAuth(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  // FOLDER NESTING. Main_php opens NO folder around its children — it
+  // writes `<sdk>_sdk.php`, `features.php` and (inside `Folder('.')`)
+  // `config.php` straight into the target root, and each sibling component
+  // opens its own single level (EntityTypes -> `types/`, Entity ->
+  // `entity/`, Test -> `test/`). The template this replaces lived at
+  // `tm/php/utility/PrepareAuth.php` and the blanket Copy puts `tm/php/*`
+  // at the target root, so the generated file belongs at `utility/`, one
+  // folder deep. (This is NOT the ts layout: there Main already opens
+  // `src`, so PrepareAuth_ts must not open a second one.)
+  Folder({ name: 'utility' }, () => {
+    File({ name: 'PrepareAuth.' + target.ext }, () => {
+      Content(render({
+        Name: model.const.Name,
+        active: authSwitchedOn(model),
+        where: resolveAuthIn(model),
+        name: resolveAuthName(model),
+        basic: isHttpBasicAuth(model),
+        // Read so the resolution is exercised here too, even though the
+        // prefix is a RUNTIME option (`options.auth.prefix`, emitted by
+        // Config_php) rather than something baked into this file.
+        prefix: resolveAuthPrefix(model),
+      }))
+    })
+  })
+})
+
+
+// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING (the py port found
+// this first; same reasoning, same fix, and php's own lane proves it here).
+//
+// `isAuthActive` is false whenever the SPEC declares no security scheme
+// (`main.kit.info.auth: false`). That is a statement about the DEFINITION,
+// not a ban on ever sending a credential: apidef writes it for every spec
+// with no securitySchemes block, GitHub's official OpenAPI included, and
+// those SDKs are still expected to honour an `apikey` the caller passes.
+// The template placed the credential unconditionally, so they did.
+//
+// Gating the body on `isAuthActive` therefore does not trim dead code, it
+// deletes working authentication. MEASURED, not assumed: with the wider gate
+// this component emitted the no-op for generatedcompile's own fixture
+// (`main: kit: info: { ... auth: false }`) and the php lane went red —
+//
+//   php: auth null beats an explicit apikey
+//     FAIL: baseline broken: an ordinary apikey was not sent
+//
+// So the no-op is emitted only when the PROJECT says so:
+// `config.auth.active: false`, an explicit per-SDK switch nobody sets by
+// accident. A spec that is merely silent keeps the credential path it has
+// always had.
+function authSwitchedOn(model: any): boolean {
+  const auth = getModelPath(model, `main.${KIT}.config.auth`,
+    { only_active: false, required: false })
+  return !(null != auth && false === auth.active)
+}
+
+
+type AuthSpec = {
+  Name: string,
+  active: boolean,
+  where: string,
+  name: string,
+  basic: boolean,
+  prefix: string,
+}
+
+
+function render(spec: AuthSpec): string {
+  const Name = spec.Name
+
+  const head = `<?php
+declare(strict_types=1);
+
+// ${Name} SDK utility: prepare_auth
+
+`
+
+  // AUTH SWITCHED OFF BY THE PROJECT (see authSwitchedOn for why only an
+  // EXPLICIT switch counts). The SDK gets a prepare_auth that is honest
+  // about it rather than one that deletes a header nobody set.
+  if (!spec.active) {
+    return head + `// This SDK is configured with authentication off, so there is no
+// credential to place. The class stays in the pipeline because make_spec
+// calls prepare_auth unconditionally.
+class ${Name}PrepareAuth
+{
+    public static function call(${Name}Context $ctx): array
+    {
+        $spec = $ctx->spec;
+        if (!$spec) {
+            return [null, $ctx->make_error('auth_no_spec', 'Expected context spec property to be defined.')];
+        }
+
+        return [$spec, null];
+    }
+}
+`
+  }
+
+  const bag = bagVar(spec.where)
+
+  return head + `class ${Name}PrepareAuth
+{
+${constants(spec)}
+    public static function call(${Name}Context $ctx): array
+    {
+        $spec = $ctx->spec;
+        if (!$spec) {
+            return [null, $ctx->make_error('auth_no_spec', 'Expected context spec property to be defined.')];
+        }
+
+        $${bag} = &$spec->${bag};
+        $options = $ctx->client->options_map();
+
+        // Public APIs that need no auth omit the options.auth block entirely.
+        if (!isset($options['auth']) || $options['auth'] === null) {
+${suppressed(spec.where)}            return [$spec, null];
+        }
+
+        $apikey = \\Voxgig\\Struct\\Struct::getprop($options, self::OPTION_APIKEY, self::NOT_FOUND);
+${basicBlock(spec)}${placeBlock(spec)}
+        return [$spec, null];
+    }
+}
+`
+}
+
+
+// The bag the credential lands in, per placement. Cookies ride the header
+// bag because a cookie IS a header.
+function bagVar(where: string): string {
+  return 'query' === where ? 'query' : 'headers'
+}
+
+
+// The constant holding the credential's NAME, per placement. `HEADER_AUTH`
+// keeps the name the template used, so a header SDK regenerates unchanged.
+function credConst(where: string): string {
+  return 'query' === where ? 'QUERY_AUTH' : 'cookie' === where ? 'COOKIE_AUTH' : 'HEADER_AUTH'
+}
+
+
+function constants(spec: AuthSpec): string {
+  // A HEADER NAME GOES IN LOWERCASE, as every target's template has always
+  // written it (`authorization`): request header names are case-insensitive,
+  // and this SDK's own response headers are lowercased by the fetcher, so
+  // lowercasing here keeps one spelling throughout — and keeps the default
+  // byte-identical to the template this replaces. A query parameter and a
+  // cookie name are CASE-SENSITIVE, so those go in verbatim.
+  const name = 'header' === spec.where ? spec.name.toLowerCase() : spec.name
+
+  const cookieConst = 'cookie' === spec.where ?
+    `    private const HEADER_COOKIE = 'cookie';\n` : ''
+
+  const secretConst = basicActive(spec) ?
+    `    private const OPTION_SECRET = 'secret';\n` : ''
+
+  return `    private const ${credConst(spec.where)} = ${phpstr(name)};
+${cookieConst}    private const OPTION_APIKEY = 'apikey';
+${secretConst}    private const NOT_FOUND = '__NOTFOUND__';
+`
+}
+
+
+// The `options.auth` block is absent (`auth: null`) — drop any stale
+// credential the caller's own options put in the bag.
+function suppressed(where: string): string {
+  if ('cookie' === where) {
+    // NOTHING TO CLEAR. The cookie header may carry the caller's own
+    // cookies, and this SDK has not written a pair of its own into this
+    // spec, so removing the header would throw away someone else's state.
+    return ''
+  }
+  return `            unset($${bagVar(where)}[self::${credConst(where)}]);\n`
+}
+
+
+// HTTP Basic is header-only by definition: the scheme is
+// `Authorization: Basic base64(user:pass)`. It cannot be expressed as a
+// query parameter or a cookie, so the branch is emitted only where it can
+// mean something.
+function basicActive(spec: AuthSpec): boolean {
+  return spec.basic && 'header' === spec.where
+}
+
+
+function basicBlock(spec: AuthSpec): string {
+  if (!basicActive(spec)) {
+    return ''
+  }
+
+  return `
+        // True HTTP Basic Auth needs TWO credentials, base64-joined - a
+        // single token in the header (the branch below) can never
+        // authenticate against an API that actually checks
+        // \`Authorization: Basic base64(user:pass)\`.
+        if (true === (\\Voxgig\\Struct\\Struct::getpath($options, 'auth.basic') ?? false)) {
+            $secret = \\Voxgig\\Struct\\Struct::getprop($options, self::OPTION_SECRET, self::NOT_FOUND);
+            $apikey_val = is_string($apikey) && $apikey !== self::NOT_FOUND ? $apikey : '';
+            $secret_val = is_string($secret) && $secret !== self::NOT_FOUND ? $secret : '';
+
+            if ($apikey_val === '' || $secret_val === '') {
+                unset($headers[self::HEADER_AUTH]);
+            } else {
+                $auth_prefix = \\Voxgig\\Struct\\Struct::getpath($options, 'auth.prefix') ?? '';
+                $b64 = base64_encode("{$apikey_val}:{$secret_val}");
+                $headers[self::HEADER_AUTH] = $auth_prefix === ''
+                    ? $b64 : "{$auth_prefix} {$b64}";
+            }
+
+            return [$spec, null];
+        }
+`
+}
+
+
+function placeBlock(spec: AuthSpec): string {
+  const missing = `(is_string($apikey) && ($apikey === self::NOT_FOUND || $apikey === ''))
+            || $apikey === null`
+
+  if ('cookie' === spec.where) {
+    // A MISSING CREDENTIAL CLEARS NOTHING HERE, for the reason `suppressed`
+    // gives: the cookie header is shared with the caller's own cookies.
+    return `
+        $missing = ${missing};
+
+        if (!$missing) {
+            // A COOKIE IS APPENDED, NEVER ASSIGNED: the header may already
+            // carry the caller's own cookies, and one \`Cookie:\` header
+            // holds all of them, separated by '; '.
+            $apikey_val = is_string($apikey) ? $apikey : '';
+            $existing = $headers[self::HEADER_COOKIE] ?? '';
+            $pair = self::COOKIE_AUTH . '=' . $apikey_val;
+            $headers[self::HEADER_COOKIE] = $existing === ''
+                ? $pair : "{$existing}; {$pair}";
+        }
+`
+  }
+
+  if ('query' === spec.where) {
+    return `
+        if (
+            ${missing}
+        ) {
+            unset($query[self::QUERY_AUTH]);
+        } else {
+            // NO PREFIX IN A QUERY STRING. \`?token=Bearer%20abc\` is not a
+            // thing any API reads; the prefix is a header convention and is
+            // dropped here deliberately rather than silently concatenated.
+            $query[self::QUERY_AUTH] = is_string($apikey) ? $apikey : '';
+        }
+`
+  }
+
+  return `
+        if (
+            ${missing}
+        ) {
+            unset($headers[self::HEADER_AUTH]);
+        } else {
+            $auth_prefix = \\Voxgig\\Struct\\Struct::getpath($options, 'auth.prefix') ?? '';
+            $apikey_val = is_string($apikey) ? $apikey : '';
+            // Empty prefix (raw apiKey credential) must not add a leading space.
+            $headers[self::HEADER_AUTH] = $auth_prefix === ''
+                ? $apikey_val : "{$auth_prefix} {$apikey_val}";
+        }
+`
+}
+
+
+// A PHP single-quoted string literal: only the backslash and the quote
+// itself need escaping, and single quotes never interpolate a `$name`.
+function phpstr(s: string): string {
+  return "'" + String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'"
+}
+
+
+export {
+  PrepareAuth,
+  // Exported so the emitted PHP can be exercised directly (tests, and a
+  // one-line check of what a given placement renders) without standing up a
+  // full generation run.
+  render,
+}

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

@@ -20,6 +20,7 @@ Use \`Helpers::to_map()\` to safely validate that a value is an array.
 php/
 ├── ${model.const.Name.toLowerCase()}_sdk.php          -- Main SDK class
 ├── config.php                     -- Configuration
+├── schema.php                     -- Generated option + entity specs
 ├── features.php                   -- Feature factory
 ├── core/                          -- Core types and context
 ├── entity/                        -- Entity implementations

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

@@ -0,0 +1,129 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+  rawStringLiteral,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The php peer of src/cmp/ts/Schema_ts.ts. Same two exports, same source —
+// OPTSPEC from `main.kit.optspec` plus each feature's own `config.options`,
+// ENTITYSPEC from the entity field sentinels — built by the shared helpers,
+// so what php validates against and what ts validates against cannot drift.
+//
+// EMBEDDED AS JSON, DECODED ON FIRST USE, the mechanism config.php already
+// uses for the model above the size threshold, and SINGLE-quoted for the
+// reason recorded there: a double-quoted php string would interpolate a `$`,
+// and the spec is made almost entirely of `$SENTINEL` strings.
+//
+// The round-trip is exact because the spec holds only strings and booleans —
+// pinned by "strings and booleans only, so the JSON round-trip is lossless"
+// in ts/test/optspec.test.ts.
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  File({ name: 'schema.' + target.ext }, () => {
+    Content(`<?php
+declare(strict_types=1);
+
+// ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+//
+// Generated from the model: \`main.kit.optspec\` and each feature's
+// \`config.options\` for OPTSPEC; entity \`fields[].type\` for ENTITYSPEC.
+
+class ${model.const.Name}Schema
+{
+    private const OPTSPEC_DATA = ${rawStringLiteral(JSON.stringify(optspec))};
+
+    private const ENTITYSPEC_DATA = ${rawStringLiteral(JSON.stringify(entityspec))};
+
+    // A UNION, not ?array. schema_decode hands back an empty stdClass for an
+    // EMPTY map - that is the whole point of decoding without the assoc flag,
+    // since php cannot otherwise tell an empty map from an empty list - and
+    // the entity specs are empty for a project with no entities, and whenever
+    // the validate feature is inactive, which is the default. Typed ?array,
+    // the first call to entityspec() threw a TypeError instead of handing
+    // back the empty map every other target returns.
+    private static array|\\stdClass|null $optspec = null;
+
+    private static array|\\stdClass|null $entityspec = null;
+
+    // Decoded ONCE, on first use. The spec is read on every client
+    // construction and never mutated, so decoding per call would be pure
+    // waste — and sharing the array is safe for the same reason:
+    // make_options validates AGAINST it and writes into the options, never
+    // into the spec. (php arrays are copy-on-write, so a caller that did
+    // write would get its own copy rather than corrupt this one.)
+    public static function optspec(): array|\\stdClass
+    {
+        if (self::$optspec === null) {
+            self::$optspec = self::schema_decode(json_decode(self::OPTSPEC_DATA));
+        }
+        return self::$optspec;
+    }
+
+    public static function entityspec(): array|\\stdClass
+    {
+        if (self::$entityspec === null) {
+            self::$entityspec = self::schema_decode(json_decode(self::ENTITYSPEC_DATA));
+        }
+        return self::$entityspec;
+    }
+
+    /**
+     * Decode WITHOUT the assoc flag, then convert — for the one reason
+     * config.php decodes the same way.
+     *
+     * php has a single array type, so json_decode with the assoc flag
+     * renders an empty object and an empty list identically. Struct tells a
+     * map from a list, so every empty map in the spec — utility, a feature's
+     * rates, the OPEN-only entity template — arrived as an empty LIST and
+     * was rejected with "Expected map, but found no value". Decoding to
+     * stdClass keeps the distinction long enough to preserve it.
+     *
+     * config.php patches its two known empty maps by hand afterwards; the
+     * spec has too many to enumerate and would gain one whenever a feature
+     * declares a map option, so this restores every one of them by shape.
+     */
+    private static function schema_decode(mixed $v): mixed
+    {
+        if ($v instanceof \\stdClass) {
+            $vars = get_object_vars($v);
+            if (count($vars) === 0) {
+                return (object)[];
+            }
+            $out = [];
+            foreach ($vars as $k => $c) {
+                $out[$k] = self::schema_decode($c);
+            }
+            return $out;
+        }
+        if (is_array($v)) {
+            return array_map([self::class, 'schema_decode'], $v);
+        }
+        return $v;
+    }
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

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

@@ -13,6 +13,8 @@ import {
   each,
   isAuthActive,
   isConfigData,
+  resolveAuthIn,
+  resolveAuthName,
   resolveAuthPrefix,
   serverVariables,
   targetFeatures,
@@ -107,6 +109,13 @@ const Config = cmp(async function Config(props: any) {
   const authActive = isAuthActive(model)
   // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
   const authPrefix = resolveAuthPrefix(model)
+  // `in` and `name` travel with the prefix now. They were resolved by
+  // apidef all along and dropped here, so an apiKey-in-query API got an
+  // Authorization header it does not read. Emitted only when they differ
+  // from the defaults, so a header/Authorization SDK is byte-identical to
+  // what it generated before.
+  const authIn = resolveAuthIn(model)
+  const authName = resolveAuthName(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
@@ -121,7 +130,9 @@ const Config = cmp(async function Config(props: any) {
 
   const authBlock = authActive
     ? `            "auth": {
-                "prefix": "${authPrefix}",
+                "prefix": "${authPrefix}",${'header' === authIn ? '' : `
+                "in": "${authIn}",`}${'Authorization' === authName ? '' : `
+                "name": "${authName}",`}
             },\n`
     : ''
 

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

@@ -24,6 +24,8 @@ import {
 
 import { Package } from './Package_py'
 import { Config } from './Config_py'
+import { Schema } from './Schema_py'
+import { PrepareAuth } from './PrepareAuth_py'
 import { Gitignore } from './Gitignore_py'
 import { MainEntity } from './MainEntity_py'
 import { EntityTypes } from './EntityTypes_py'
@@ -188,8 +190,20 @@ if TYPE_CHECKING:
   // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
+    Schema({ target })
   })
 
+  // GENERATED, NOT COPIED. Where the credential goes is a fact about the
+  // API, and tm/ can only hold one answer. The blanket tm/py/pkg copy above
+  // no longer brings a prepare_auth.py in - it was deleted, since both
+  // writers would claim the same output path. See PrepareAuth_py.
+  //
+  // Called HERE, inside the <name>_sdk package folder and outside any
+  // other, because that is where the deleted template's own path
+  // (tm/py/pkg/utility/prepare_auth.py) put it: the component opens the one
+  // remaining segment, `utility`, itself.
+  PrepareAuth({ target })
+
   // Generate feature factory module
   File({ name: 'features.' + target.ext }, () => {
     Content(`# ${model.const.Name} SDK feature factory