@voxgig/sdkgen 1.5.1 → 2.0.0

package/project/.sdk/src/cmp/lua/fragment/Main.fragment.lua

@@ -179,7 +179,41 @@ function ProjectNameSDK:prepare(fetchargs)
 end
 
 
+-- Raw endpoint access is operator-controllable, like every entity op.
+-- Blocking it means denying BOTH the 'direct' and 'graphql' tokens, since
+-- either one reaches the same endpoint.
 function ProjectNameSDK:direct(fetchargs)
+  if not self:_op_allowed("direct") then
+    return self:_op_denied("direct"), nil
+  end
+
+  return self:_raw_request(fetchargs)
+end
+
+
+-- Is this raw-access op permitted by the SDK's allow.op option?
+function ProjectNameSDK:_op_allowed(op)
+  local allow = vs.getpath(self.options, "allow.op")
+  return type(allow) == "string" and allow:find(op, 1, true) ~= nil
+end
+
+
+function ProjectNameSDK:_op_denied(op)
+  local allow = vs.getpath(self.options, "allow.op")
+  if type(allow) ~= "string" then allow = "" end
+  return {
+    ok = false,
+    err = "ProjectNameSDK: " .. op .. ": operation not allowed by" ..
+      " SDK option allow.op value: \"" .. allow .. "\"",
+  }
+end
+
+
+-- Ungated request path shared by direct and graphql, each of which checks its
+-- own allow.op token first. Private, rather than a flag on fetchargs: a
+-- caller-supplied marker would let anyone opt straight back out of the gate
+-- by passing it.
+function ProjectNameSDK:_raw_request(fetchargs)
   local utility = self._utility
 
   local fetchdef, err = self:prepare(fetchargs)
@@ -248,6 +282,57 @@ function ProjectNameSDK:direct(fetchargs)
 end
 
 
+-- Raw GraphQL access: the pressure valve that makes the generated surface's
+-- deliberate omissions (per-call selection sets, typed filter builders,
+-- batching, subscriptions) livable — the whole schema stays reachable.
+--
+-- Thin wrapper over the same prepare/fetch path direct uses, with the one
+-- thing raw direct cannot do for GraphQL: a GraphQL failure rides HTTP 200 as
+-- a top-level `errors` array, so status alone would report a failed query as
+-- ok.
+--
+-- NOTE: like direct, this bypasses the feature pipeline — no retry, ratelimit
+-- or paging features apply.
+function ProjectNameSDK:graphql(query, variables, ctrl)
+  if not self:_op_allowed("graphql") then
+    return self:_op_denied("graphql"), nil
+  end
+
+  local res, err = self:_raw_request({
+    method = "POST",
+    headers = { ["content-type"] = "application/json" },
+    body = {
+      query = query,
+      variables = type(variables) == "table" and variables or {},
+    },
+    ctrl = type(ctrl) == "table" and ctrl or {},
+  })
+
+  if err ~= nil or type(res) ~= "table" then
+    return res, err
+  end
+
+  -- Errors are read BEFORE any status check: a GraphQL parse or validation
+  -- failure comes back as HTTP 400 carrying the standard { errors = {...} }
+  -- body, and the raw path represents a non-2xx as ok=false with no err — so
+  -- returning early on status would discard the server's own diagnostics,
+  -- which are the only useful part of that response.
+  local errors = vs.getpath(res, "data.errors")
+
+  if type(errors) == "table" and 0 < #errors then
+    local msg = vs.getprop(errors[1], "message")
+    if type(msg) ~= "string" or msg == "" then
+      msg = "graphql error"
+    end
+    res.ok = false
+    res.err = "ProjectNameSDK: graphql: " .. msg
+    res.graphql = errors
+  end
+
+  return res, nil
+end
+
+
 -- <[SLOT]>
 
 

package/project/.sdk/src/cmp/ocaml/Main_ocaml.ts

@@ -94,6 +94,10 @@ let test_with (testopts : value) (sdkopts : value) : sdk_client =
 let direct (client : sdk_client) (fetchargs : value) : value =
   Sdk_features.direct client fetchargs
 
+let graphql (client : sdk_client) (query : string) (variables : value)
+    (ctrl : value) : value =
+  Sdk_features.graphql client query variables ctrl
+
 let prepare (client : sdk_client) (fetchargs : value) : value =
   Sdk_features.prepare client fetchargs
 `)

package/project/.sdk/src/cmp/perl/fragment/Main.fragment.pm

@@ -172,8 +172,41 @@ sub prepare {
   return $fetchdef;
 }
 
+# Raw endpoint access is operator-controllable, like every entity op.
+# Blocking it means denying BOTH the 'direct' and 'graphql' tokens, since
+# either one reaches the same endpoint.
 sub direct {
   my ($self, $fetchargs) = @_;
+
+  return $self->_op_denied('direct') unless $self->_op_allowed('direct');
+
+  return $self->_raw_request($fetchargs);
+}
+
+# Is this raw-access op permitted by the SDK's allow.op option?
+sub _op_allowed {
+  my ($self, $op) = @_;
+  my $allow = ProjectNameHelpers::gpath($self->{options}, 'allow.op');
+  return (defined $allow && !ref $allow && index($allow, $op) >= 0) ? 1 : 0;
+}
+
+sub _op_denied {
+  my ($self, $op) = @_;
+  my $allow = ProjectNameHelpers::gpath($self->{options}, 'allow.op');
+  $allow = '' unless defined $allow && !ref $allow;
+  return {
+    'ok' => 0,
+    'err' => "ProjectNameSDK: $op: operation not allowed by" .
+      " SDK option allow.op value: \"$allow\"",
+  };
+}
+
+# Ungated request path shared by direct and graphql, each of which checks its
+# own allow.op token first. Private, rather than a flag on fetchargs: a
+# caller-supplied marker would let anyone opt straight back out of the gate
+# by passing it.
+sub _raw_request {
+  my ($self, $fetchargs) = @_;
   my $utility = $self->{_utility};
 
   # direct() is the raw-HTTP escape hatch: it always returns a result hash
@@ -240,6 +273,53 @@ sub direct {
   };
 }
 
+# Raw GraphQL access: the pressure valve that makes the generated surface's
+# deliberate omissions (per-call selection sets, typed filter builders,
+# batching, subscriptions) livable — the whole schema stays reachable.
+#
+# Thin wrapper over the same prepare/fetch path direct uses, with the one
+# thing raw direct cannot do for GraphQL: a GraphQL failure rides HTTP 200 as
+# a top-level `errors` array, so status alone would report a failed query as
+# ok.
+#
+# NOTE: like direct, this bypasses the feature pipeline — no retry, ratelimit
+# or paging features apply.
+sub graphql {
+  my ($self, $query, $variables, $ctrl) = @_;
+
+  return $self->_op_denied('graphql') unless $self->_op_allowed('graphql');
+
+  my $res = $self->_raw_request({
+    'method' => 'POST',
+    'headers' => { 'content-type' => 'application/json' },
+    'body' => {
+      'query' => defined $query ? $query : '',
+      'variables' => (ref $variables eq 'HASH') ? $variables : {},
+    },
+    'ctrl' => (ref $ctrl eq 'HASH') ? $ctrl : {},
+  });
+
+  return $res unless ref $res eq 'HASH';
+
+  # Errors are read BEFORE any status check: a GraphQL parse or validation
+  # failure comes back as HTTP 400 carrying the standard { errors: [...] }
+  # body, and the raw path represents a non-2xx as ok:0 with no err — so
+  # returning early on status would discard the server's own diagnostics,
+  # which are the only useful part of that response.
+  my $errors = ProjectNameHelpers::gpath($res, 'data.errors');
+
+  if (ref $errors eq 'ARRAY' && 0 < scalar @$errors) {
+    my $first = $errors->[0];
+    my $msg = (ref $first eq 'HASH') ? $first->{'message'} : undef;
+    $msg = 'graphql error' unless defined $msg && $msg ne '';
+    $res->{'ok'} = 0;
+    $res->{'err'} = "ProjectNameSDK: graphql: $msg";
+    $res->{'graphql'} = $errors;
+  }
+
+  return $res;
+}
+
 # <[SLOT]>
 
 sub test {

package/project/.sdk/src/cmp/php/fragment/Main.fragment.php

@@ -166,7 +166,41 @@ class ProjectNameSDK
         return $fetchdef;
     }
 
+    // Raw endpoint access is operator-controllable, like every entity op.
+    // Blocking it means denying BOTH the 'direct' and 'graphql' tokens,
+    // since either one reaches the same endpoint.
     public function direct(array $fetchargs = []): mixed
+    {
+        if (!$this->op_allowed("direct")) {
+            return $this->op_denied("direct");
+        }
+
+        return $this->raw_request($fetchargs);
+    }
+
+    // Is this raw-access op permitted by the SDK's allow.op option?
+    private function op_allowed(string $op): bool
+    {
+        $allow_op = Struct::getpath($this->options, "allow.op");
+        return is_string($allow_op) && str_contains($allow_op, $op);
+    }
+
+    private function op_denied(string $op): array
+    {
+        $allow_op = Struct::getpath($this->options, "allow.op");
+        return [
+            "ok" => false,
+            "err" => new ProjectNameError($op . "_allow",
+                "ProjectNameSDK: " . $op . ": operation not allowed by" .
+                " SDK option allow.op value: \"" . (string)$allow_op . "\""),
+        ];
+    }
+
+    // Ungated request path shared by direct and graphql, each of which
+    // checks its own allow.op token first. Private, rather than a flag on
+    // fetchargs: a caller-supplied marker would let anyone opt straight back
+    // out of the gate by passing it.
+    private function raw_request(array $fetchargs = []): mixed
     {
         $utility = $this->_utility;
 
@@ -237,6 +271,58 @@ class ProjectNameSDK
         ];
     }
 
+    // Raw GraphQL access: the pressure valve that makes the generated
+    // surface's deliberate omissions (per-call selection sets, typed filter
+    // builders, batching, subscriptions) livable — the whole schema stays
+    // reachable.
+    //
+    // Thin wrapper over the same prepare/fetch path direct uses, with the
+    // one thing raw direct cannot do for GraphQL: a GraphQL failure rides
+    // HTTP 200 as a top-level `errors` array, so status alone would report
+    // a failed query as ok.
+    //
+    // NOTE: like direct, this bypasses the feature pipeline — no retry,
+    // ratelimit or paging features apply.
+    public function graphql(string $query, ?array $variables = null, ?array $ctrl = null): mixed
+    {
+        if (!$this->op_allowed("graphql")) {
+            return $this->op_denied("graphql");
+        }
+
+        $res = $this->raw_request([
+            "method" => "POST",
+            "headers" => ["content-type" => "application/json"],
+            "body" => ["query" => $query, "variables" => $variables ?? []],
+            "ctrl" => $ctrl ?? [],
+        ]);
+
+        if (!is_array($res)) {
+            return $res;
+        }
+
+        // Errors are read BEFORE any status check: a GraphQL parse or
+        // validation failure comes back as HTTP 400 carrying the standard
+        // { errors: [...] } body, and the raw path represents a non-2xx as
+        // ok:false with no err — so returning early on status would discard
+        // the server's own diagnostics, which are the only useful part of
+        // that response.
+        $errors = Struct::getpath($res, "data.errors");
+
+        if (is_array($errors) && 0 < count($errors)) {
+            $first = is_array($errors[0]) ? $errors[0] : [];
+            $msg = $first["message"] ?? "";
+            if (!is_string($msg) || "" === $msg) {
+                $msg = "graphql error";
+            }
+            $res["ok"] = false;
+            $res["err"] = new ProjectNameError("graphql_error",
+                "ProjectNameSDK: graphql: " . $msg);
+            $res["graphql"] = $errors;
+        }
+
+        return $res;
+    }
+
     // <[SLOT]>
 
     public static function test(?array $testopts = null, ?array $sdkopts = null): self

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

@@ -41,14 +41,20 @@ const Entity = cmp(function Entity(props: any) {
       typeNames.push(opTypeName(entity.Name, opname))
     }
   })
-  const typesModule = model.const.Name.toLowerCase() + '_types'
+  // The generated dataclasses live inside the SDK package alongside
+  // everything else, so the import is package-qualified.
+  const typesModule = model.const.Name.toLowerCase() + '_sdk.' +
+    model.const.Name.toLowerCase() + '_types'
   const typeImport =
     'from ' + typesModule + ' import (\n    ' +
     typeNames.join(',\n    ') + ',\n)'
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/py/fragment/')
 
-  // Entity files go to entity/ folder
+  // Entity files go to <name>_sdk/entity/ — inside the SDK package, not at
+  // the language root. See the note in Main_py.ts: a top-level `entity`
+  // package is shadowable by any entity.py sitting beside the caller.
+  Folder({ name: model.const.Name.toLowerCase() + '_sdk' }, () => {
   Folder({ name: 'entity' }, () => {
 
     File({ name: entity.name + '_entity.' + target.ext }, () => {
@@ -95,6 +101,7 @@ const Entity = cmp(function Entity(props: any) {
 
     })
   })
+  })
 })
 
 

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

@@ -20,7 +20,7 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   Content(`
     def ${entity.Name}(self, data=None) -> "${cls}":
         """Entity factory: client.${entity.Name}().list() / client.${entity.Name}().load({"id": ...})."""
-        from entity.${entity.name}_entity import ${cls}
+        from ${model.const.Name.toLowerCase()}_sdk.entity.${entity.name}_entity import ${cls}
         return ${cls}(self, data)
 
 `)

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

@@ -34,21 +34,47 @@ const Main = cmp(async function Main(props: any) {
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
+  // The one package directory everything the SDK owns lives in.
+  const pkgdir = model.const.Name.toLowerCase() + '_sdk'
+
   Package({ target })
 
   Gitignore({})
 
-  // Copy tm/py files with replacements
+  // Root-level statics only (Makefile, LICENSE, test/). The runtime
+  // packages live under tm/py/pkg and are copied INSIDE the SDK package
+  // below.
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//],
+    exclude: [/src\//, /pkg\//],
+    replace: {
+      ...props.ctx$.stdrep,
+    }
+  })
+
+  // Everything the SDK owns lives inside ONE package directory.
+  //
+  // core/, entity/, feature/ and utility/ used to sit at the language root
+  // as top-level importable names. `core`, `entity` and `utility` are all
+  // real PyPI distributions AND common scratch filenames, and Python puts
+  // the working directory first on sys.path — so a single utility.py beside
+  // a notebook shadowed ours and the SDK died on
+  // `No module named 'utility.voxgig_struct'`. Nesting them behind the
+  // model-named package makes that impossible.
+  //
+  // The public import is unchanged: `from <name>_sdk import <Name>SDK`,
+  // because <name>_sdk.py becomes <name>_sdk/__init__.py.
+  Folder({ name: pkgdir }, () => {
+
+  Copy({
+    from: 'tm/' + target.name + '/pkg',
     replace: {
       ...props.ctx$.stdrep,
     }
   })
 
   // Generate main SDK file
-  File({ name: model.const.Name.toLowerCase() + '_sdk.' + target.ext }, () => {
+  File({ name: '__init__.' + target.ext }, () => {
 
     Fragment(
       {
@@ -94,7 +120,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
 `)
       each(entity, (ent: any) => {
-        Content(`    from entity.${ent.name}_entity import ${entityClassName(ent, entityCollection(model))}
+        Content(`    from ${model.const.Name.toLowerCase()}_sdk.entity.${ent.name}_entity import ${entityClassName(ent, entityCollection(model))}
 `)
       })
     }
@@ -119,13 +145,13 @@ if TYPE_CHECKING:
   File({ name: 'features.' + target.ext }, () => {
     Content(`# ${model.const.Name} SDK feature factory
 
-from feature.base_feature import ${model.const.Name}BaseFeature
+from ${model.const.Name.toLowerCase()}_sdk.feature.base_feature import ${model.const.Name}BaseFeature
 `)
 
     each(feature, (feat: any) => {
       if (feat.name !== 'base') {
         const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
-        Content(`from feature.${feat.name}_feature import ${model.const.Name}${fname}Feature
+        Content(`from ${model.const.Name.toLowerCase()}_sdk.feature.${feat.name}_feature import ${model.const.Name}${fname}Feature
 `)
       }
     })
@@ -187,6 +213,8 @@ def _make_feature(name):
     })
   })
 
+  })
+
 })
 
 

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

@@ -62,16 +62,13 @@ Homepage = "${repoUrl}"
 Repository = "${repoUrl}"
 Issues = "${issuesUrl}"
 
-# Ship the top-level single-file modules (setuptools find only discovers
-# package dirs, never these) so the documented import actually installs.
-# ${model.const.Name.toLowerCase()}_types holds the generated @dataclass models.
-[tool.setuptools]
-py-modules = ["${model.const.Name.toLowerCase()}_sdk", "${model.const.Name.toLowerCase()}_types", "config", "features"]
-
-# Explicit package list — setuptools auto-discovery refuses to pick when
-# multiple top-level dirs (core/entity/feature/utility) are present.
+# ONE package. core/entity/feature/utility were previously top-level packages;
+# those names are real PyPI distributions and common scratch filenames, and
+# Python searches the working directory first, so any of them beside the
+# caller silently shadowed the SDK's own. They now live inside
+# ${model.const.Name.toLowerCase()}_sdk/ where nothing can reach them.
 [tool.setuptools.packages.find]
-include = ["core*", "entity*", "feature*", "utility*"]
+include = ["${model.const.Name.toLowerCase()}_sdk*"]
 
 # Ship the PEP 561 py.typed marker(s) so the inline type hints reach consumers.
 [tool.setuptools.package-data]

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

@@ -137,9 +137,9 @@ const TestDirect = cmp(function TestDirect(props: any) {
 import json
 import pytest
 
-from utility.voxgig_struct import voxgig_struct as vs
+from ${model.const.Name.toLowerCase()}_sdk.utility.voxgig_struct import voxgig_struct as vs
 from ${model.const.Name.toLowerCase()}_sdk import ${model.const.Name}SDK
-from core import helpers
+from ${model.const.Name.toLowerCase()}_sdk.core import helpers
 from test import runner
 
 

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

@@ -94,9 +94,9 @@ import time
 
 import pytest
 
-from utility.voxgig_struct import voxgig_struct as vs
+from ${model.const.Name.toLowerCase()}_sdk.utility.voxgig_struct import voxgig_struct as vs
 from ${model.const.Name.toLowerCase()}_sdk import ${model.const.Name}SDK
-from core import helpers
+from ${model.const.Name.toLowerCase()}_sdk.core import helpers
 
 _TEST_DIR = os.path.dirname(os.path.abspath(__file__))
 from test import runner
@@ -130,7 +130,7 @@ ${hasList ? `
         assert len(seen) == 3
 
         # Inbound: streaming active -> yields each item from the feature.
-        from config import make_config
+        from ${model.const.Name.toLowerCase()}_sdk.config import make_config
         cfg = make_config()
         if isinstance(cfg.get("feature"), dict) and "streaming" in cfg["feature"]:
             sdk = ${model.const.Name}SDK.test(

package/project/.sdk/src/cmp/py/fragment/Entity.fragment.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from utility.voxgig_struct import voxgig_struct as vs
-from core import helpers
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.core import helpers
 # #TypeImports
 
 

package/project/.sdk/src/cmp/py/fragment/EntityCreateOp.fragment.py

@@ -1,5 +1,5 @@
-from utility.voxgig_struct import voxgig_struct as vs
-from core import helpers
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.core import helpers
 
 entity_create_op = None
 

package/project/.sdk/src/cmp/py/fragment/EntityLoadOp.fragment.py

@@ -1,5 +1,5 @@
-from utility.voxgig_struct import voxgig_struct as vs
-from core import helpers
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.core import helpers
 
 entity_load_op = None
 

package/project/.sdk/src/cmp/py/fragment/EntityRemoveOp.fragment.py

@@ -1,5 +1,5 @@
-from utility.voxgig_struct import voxgig_struct as vs
-from core import helpers
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.core import helpers
 
 entity_remove_op = None
 

package/project/.sdk/src/cmp/py/fragment/EntityUpdateOp.fragment.py

@@ -1,5 +1,5 @@
-from utility.voxgig_struct import voxgig_struct as vs
-from core import helpers
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.core import helpers
 
 entity_update_op = None
 

package/project/.sdk/src/cmp/py/fragment/Main.fragment.py

@@ -1,16 +1,16 @@
 # ProjectName SDK
 
-from utility.voxgig_struct import voxgig_struct as vs
-from core.utility_type import ProjectNameUtility
-from core.spec import ProjectNameSpec
-from core import helpers
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.core.utility_type import ProjectNameUtility
+from projectname_sdk.core.spec import ProjectNameSpec
+from projectname_sdk.core import helpers
 
 # Load utility registration (populates Utility._registrar)
-from utility import register
+from projectname_sdk.utility import register
 
 # Load features
-from feature.base_feature import ProjectNameBaseFeature
-from features import _make_feature
+from projectname_sdk.feature.base_feature import ProjectNameBaseFeature
+from projectname_sdk.features import _make_feature
 
 
 class ProjectNameSDK:
@@ -23,7 +23,7 @@ class ProjectNameSDK:
         utility = ProjectNameUtility()
         self._utility = utility
 
-        from config import make_config
+        from projectname_sdk.config import make_config
         config = make_config()
 
         self._rootctx = utility.make_context({
@@ -155,7 +155,34 @@ class ProjectNameSDK:
 
         return fetchdef
 
+    # Raw endpoint access is operator-controllable, like every entity op.
+    # Blocking it means denying BOTH the 'direct' and 'graphql' tokens, since
+    # either one reaches the same endpoint.
     def direct(self, fetchargs=None):
+        if not self._op_allowed("direct"):
+            return self._op_denied("direct")
+
+        return self._raw_request(fetchargs)
+
+    # Is this raw-access op permitted by the SDK's allow.op option?
+    def _op_allowed(self, op):
+        allow_op = vs.getpath(self.options, "allow.op")
+        return isinstance(allow_op, str) and op in allow_op
+
+    def _op_denied(self, op):
+        allow_op = vs.getpath(self.options, "allow.op")
+        return {
+            "ok": False,
+            "err": Exception(
+                "ProjectNameSDK: " + op + ": operation not allowed by"
+                ' SDK option allow.op value: "' + str(allow_op) + '"'),
+        }
+
+    # Ungated request path shared by direct and graphql, each of which checks
+    # its own allow.op token first. Private, rather than a flag on fetchargs:
+    # a caller-supplied marker would let anyone opt straight back out of the
+    # gate by passing it.
+    def _raw_request(self, fetchargs=None):
         utility = self._utility
 
         try:
@@ -222,6 +249,46 @@ class ProjectNameSDK:
             "err": ctx.make_error("direct_invalid", "invalid response type"),
         }
 
+    # Raw GraphQL access: the pressure valve that makes the generated
+    # surface's deliberate omissions (per-call selection sets, typed filter
+    # builders, batching, subscriptions) livable — the whole schema stays
+    # reachable.
+    #
+    # Thin wrapper over the same prepare/fetch path direct uses, with the one
+    # thing raw direct cannot do for GraphQL: a GraphQL failure rides HTTP 200
+    # as a top-level `errors` array, so status alone would report a failed
+    # query as ok.
+    #
+    # NOTE: like direct, this bypasses the feature pipeline — no retry,
+    # ratelimit or paging features apply.
+    def graphql(self, query, variables=None, ctrl=None):
+        if not self._op_allowed("graphql"):
+            return self._op_denied("graphql")
+
+        res = self._raw_request({
+            "method": "POST",
+            "headers": {"content-type": "application/json"},
+            "body": {"query": query, "variables": variables or {}},
+            "ctrl": ctrl or {},
+        })
+
+        # Errors are read BEFORE any status check: a GraphQL parse or
+        # validation failure comes back as HTTP 400 carrying the standard
+        # { errors: [...] } body, and the raw path represents a non-2xx as
+        # ok:False with no err — so returning early on status would discard
+        # the server's own diagnostics, which are the only useful part of
+        # that response.
+        errors = vs.getpath(res, "data.errors")
+
+        if isinstance(errors, list) and 0 < len(errors):
+            first = errors[0] if isinstance(errors[0], dict) else {}
+            msg = first.get("message") or "graphql error"
+            res["ok"] = False
+            res["err"] = Exception("ProjectNameSDK: graphql: " + str(msg))
+            res["graphql"] = errors
+
+        return res
+
     # <[SLOT]>
 
     @classmethod