@xano/sdk 1.0.0

package/dist/chunk-6IUMKYWI.js

@@ -0,0 +1,457 @@
+import {
+  resolveAuthRef
+} from "./chunk-ZDPP6RKB.js";
+import {
+  obj
+} from "./chunk-K5BBGTYZ.js";
+import {
+  assertOneOf,
+  leanInput
+} from "./chunk-XVBGLISP.js";
+import {
+  assertStoredName,
+  buildMiddlewareBlock,
+  encodeHistory
+} from "./chunk-5V5XU32D.js";
+import {
+  encodeTags,
+  registerKind,
+  resolveMockKeys
+} from "./chunk-4POWHT2K.js";
+import {
+  emitDiagnostic
+} from "./chunk-2EZ3ZJZZ.js";
+import {
+  lockKey
+} from "./chunk-6MR5TI5V.js";
+import {
+  rawResponseItems
+} from "./chunk-AKNCFVKZ.js";
+import {
+  encodeStack
+} from "./chunk-YU4HSQW7.js";
+import {
+  encodeInput
+} from "./chunk-N5GKCWE5.js";
+import {
+  deriveGuid,
+  deriveQueryGuid,
+  queryGroupComponent,
+  resolveRef
+} from "./chunk-NZOWWHU5.js";
+import {
+  getLockedCanonical
+} from "./chunk-4BW2SG2N.js";
+import {
+  describeEntry
+} from "./chunk-CIMQZRRE.js";
+
+// src/responses/response.ts
+function warnUnboundReturn(kind, name, stack, response) {
+  if (response !== void 0) return;
+  if (!Array.isArray(stack) || !stack.some((statement) => statement?.name === "mvp:return")) return;
+  emitDiagnostic({
+    severity: "warning",
+    code: "response.unbound-return",
+    message: `${kind} "${name}" ends with s.return(...) but has no \`response\` field. The value DOES come back at runtime \u2014 a top-level s.return short-circuits the stack and carries its own value out \u2014 but the stored response envelope is empty, so the shape is invisible to InferResponse, to a typed frontend, and to codegen. Declare it too: \`response: <value>\` (e.g. \`response: ref("...")\`). Where both exist, whichever executes wins \u2014 an early s.return that fires beats the declared response.`
+  });
+}
+function isValue(x) {
+  return x !== void 0 && x !== null && typeof x.tag === "string" && "value" in x && "filters" in x;
+}
+function encodeResponse(response) {
+  if (response === void 0 || response === null) {
+    return [];
+  }
+  if (typeof response !== "object" && typeof response !== "function") {
+    throw new Error(
+      `response must be a value (\`ref("x")\`, \`c.int(5)\`, \u2026) or a { key: value } record \u2014 got ${describeEntry(response)}.`
+    );
+  }
+  const carried = rawResponseItems(response);
+  if (carried !== void 0) return carried;
+  if (isValue(response)) {
+    return [
+      { filters: response.filters, name: "", tag: response.tag, value: response.value, _xsid: "", disabled: false }
+    ];
+  }
+  return Object.entries(response).map(([name, member]) => {
+    if (member === void 0) {
+      throw new Error(
+        `\`response.${name}\` is undefined \u2014 a response key takes a value (\`ref("x")\`, \`c.*\`) or a { key: value } record. Check the expression that produced it, or drop the key.`
+      );
+    }
+    const value = isValue(member) ? member : obj(member);
+    return { filters: value.filters, name, tag: value.tag, value: value.value, _xsid: "", disabled: false };
+  });
+}
+
+// src/kinds/path-params.ts
+var PARAM_MARKER = /\{([^/{}]+)\}/g;
+var NON_SEGMENT_TYPES = /* @__PURE__ */ new Set(["obj", "json", "blob", "blob_img", "blob_video", "blob_audio", "vector"]);
+function isSegmentType(type) {
+  return !NON_SEGMENT_TYPES.has(type) && !type.startsWith("geo_");
+}
+function parsePathParams(context, path) {
+  const params = [];
+  const cleaned = path.replace(/^\/+/, "");
+  let residue = "";
+  let cursor = 0;
+  for (const match of cleaned.matchAll(PARAM_MARKER)) {
+    residue += cleaned.slice(cursor, match.index);
+    cursor = match.index + match[0].length;
+    const name = match[1];
+    if (params.includes(name)) {
+      throw new Error(
+        `${context}: the path param \`${name}\` appears twice. Each {param} must be unique within one path \u2014 two segments cannot bind the same input.`
+      );
+    }
+    params.push(name);
+  }
+  residue += cleaned.slice(cursor);
+  if (residue.includes("{") || residue.includes("}")) {
+    throw new Error(
+      `${context}: "${path}" has an unmatched brace. A path param is written \`{name}\`, where the name holds no "/", "{" or "}" \u2014 it may sit anywhere in the path ("blog/{slug}", "blog/post-{slug}"), and each name must have an input of the same name to bind to.`
+    );
+  }
+  return params;
+}
+function assertPathParamInputs(context, params, inputs) {
+  for (const name of params) {
+    const descriptor = inputs?.[name];
+    if (!descriptor) {
+      throw new Error(
+        `${context}: the path declares {${name}} but there is no \`${name}\` input to bind it to, so the segment would be an inert part of the route string. Add it: input: { ${name}: input.text() }.`
+      );
+    }
+    if (descriptor.options?.array === true) {
+      throw new Error(
+        `${context}: the path param \`${name}\` cannot be a list \u2014 one path segment holds one value. Use a scalar input, or take the list as a query-string/body param under a different name.`
+      );
+    }
+    const type = descriptor.type;
+    if (!isSegmentType(type)) {
+      const article = /^[aeiou]/i.test(type) ? "an" : "a";
+      throw new Error(
+        `${context}: the path param \`${name}\` cannot be ${article} \`${type}\` \u2014 a path segment is a single string, so structured, binary, and multi-valued types have no URL form. Use a scalar input (text/int/uuid/\u2026), or move this value to a query-string or body param.`
+      );
+    }
+  }
+}
+function unboundPathParams(path, storedInput) {
+  let params;
+  try {
+    params = parsePathParams("path", path);
+  } catch {
+    return [];
+  }
+  const bound = new Set(
+    (Array.isArray(storedInput) ? storedInput : []).map(
+      (entry) => entry !== null && typeof entry === "object" ? entry.name : void 0
+    )
+  );
+  return params.filter((param) => !bound.has(param));
+}
+var DOT_SEGMENT = /^(\.|%2e){1,2}$/i;
+var CHANNEL_VALUE = /^[A-Za-z0-9_-]+$/;
+function fillPathParams(context, accessor, path, params, encode = false) {
+  const declared = parsePathParams(context, path);
+  const given = params ?? {};
+  for (const key of Object.keys(given)) {
+    if (!declared.includes(key)) {
+      throw new Error(
+        `${context}: ${accessor} was given \`${key}\`, which is not a {param} segment of the path. ` + (declared.length ? `Expected: ${declared.map((p) => `\`${p}\``).join(", ")}.` : `This path is static \u2014 call ${accessor} with no arguments.`)
+      );
+    }
+  }
+  return path.replace(PARAM_MARKER, (_all, key, at) => {
+    const value = given[key];
+    if (value === void 0 || value === null || value === "") {
+      throw new Error(
+        `${context}: ${accessor} needs a value for the path param \`${key}\` \u2014 pass { ${declared.map((p) => `${p}: \u2026 `).join(", ")}}.`
+      );
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+      throw new Error(
+        `${context}: the path param \`${key}\` is ${value} \u2014 not a finite value to put in a path.`
+      );
+    }
+    const text = String(value);
+    if (text.includes("/")) {
+      throw new Error(
+        `${context}: the path param \`${key}\` cannot contain "/" (got ${JSON.stringify(text)}) \u2014 it would fabricate a path segment and address a different route.`
+      );
+    }
+    if (!encode) {
+      if (!CHANNEL_VALUE.test(text)) {
+        throw new Error(
+          `${context}: the path param \`${key}\` is ${JSON.stringify(text)} \u2014 a channel segment holds only letters, digits, "_" and "-", so a join with it is refused.`
+        );
+      }
+      return text;
+    }
+    const segment = path.slice(path.lastIndexOf("/", at) + 1).split("/")[0].replace(PARAM_MARKER, (_m, k) => encodeURIComponent(String(given[k])));
+    if (DOT_SEGMENT.test(segment)) {
+      throw new Error(`${context}: the path param \`${key}\` makes the segment ${JSON.stringify(segment)} \u2014 URL parsers drop a "." or ".." segment, addressing another endpoint.`);
+    }
+    return encodeURIComponent(text);
+  });
+}
+
+// src/kinds/test.ts
+function testIdSeed(ownerKind, ownerName, testName) {
+  return `${ownerKind}/${ownerName}:${testName}`;
+}
+function encodeTest(def, ownerKind, ownerName) {
+  if (!def.name) throw new Error("test: `name` is required.");
+  const owner = `${ownerKind} "${ownerName}" test "${String(def.name)}"`;
+  if (def.input !== void 0 && def.input !== null && (typeof def.input !== "object" || Array.isArray(def.input))) {
+    throw new Error(`${owner}: \`input\` must be a { name: value } record \u2014 got ${describeEntry(def.input)}.`);
+  }
+  if (def.expect !== void 0 && def.expect !== null && !Array.isArray(def.expect)) {
+    throw new Error(`${owner}: \`expect\` must be a list of expectations \u2014 got ${describeEntry(def.expect)}.`);
+  }
+  const datasource = def.datasource ?? "";
+  const xdo = {
+    datasource,
+    description: def.description ?? "",
+    expect: def.expect ?? [],
+    id: def.id ?? deriveGuid("test", testIdSeed(ownerKind, ownerName, def.name)),
+    input: Object.entries(def.input ?? {}).map(([name, v]) => leanInput(name, v)),
+    name: def.name,
+    token: def.token ?? ""
+  };
+  return xdo;
+}
+function encodeTests(defs, ownerKind, ownerName) {
+  if (defs === void 0 || defs === null) return [];
+  if (!Array.isArray(defs)) {
+    throw new Error(`${ownerKind} "${ownerName}": \`tests\` must be a list of tests \u2014 got ${describeEntry(defs)}.`);
+  }
+  defs.forEach((def, i) => {
+    if (typeof def !== "object" || def === null || Array.isArray(def)) {
+      throw new Error(`${ownerKind} "${ownerName}": \`tests[${i}]\` must be a test ({ name, input, expect }) \u2014 got ${describeEntry(def)}.`);
+    }
+  });
+  const seen = /* @__PURE__ */ new Set();
+  for (const def of defs) {
+    if (seen.has(def.name)) {
+      throw new Error(
+        `${ownerKind} "${ownerName}": two tests are named "${def.name}". A test name is how a statement's \`mock\` names the test it belongs to, so names must be unique within an object. Rename one of them.`
+      );
+    }
+    seen.add(def.name);
+  }
+  return defs.map((def) => encodeTest(def, ownerKind, ownerName));
+}
+function test(def) {
+  return def;
+}
+
+// src/kinds/query.ts
+var HTTP_VERBS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
+var QUERY_RESPONSE_TYPES = ["standard", "stream"];
+function encodeExample(example) {
+  const out = {};
+  if (example?.input !== void 0 && example.input !== null) out.input = example.input;
+  if (example?.output !== void 0 && example.output !== null) out.output = example.output;
+  return out;
+}
+function defaultCache(override) {
+  return {
+    active: override !== void 0,
+    ttl: 3600,
+    input: true,
+    auth: true,
+    datasource: true,
+    ip: false,
+    headers: [],
+    env: [],
+    ...override
+  };
+}
+function resolveAuth(name, auth) {
+  return resolveAuthRef("query", name, auth);
+}
+function assertQueryPathParams(def) {
+  const context = `query "${def.name}"`;
+  assertStoredName(context, def.name, "route");
+  const params = parsePathParams(context, def.name);
+  assertPathParamInputs(context, params, def.input);
+  return params;
+}
+function assertQueryClosedSets(def) {
+  const context = `query "${def.name}"`;
+  assertOneOf(
+    context,
+    "verb",
+    def.verb,
+    HTTP_VERBS,
+    'The engine does not reject an unrecognized verb \u2014 it stores NULL, and a null verb serves as GET. So the endpoint deploys clean, answers on the wrong method, and the method you meant 404s "Unable to locate request.", which reads as a routing or api-group problem.'
+  );
+  assertOneOf(
+    context,
+    "responseType",
+    def.responseType,
+    QUERY_RESPONSE_TYPES,
+    'The engine does not reject an unrecognized response_type \u2014 it stores NULL, which falls back to "standard". So a misspelled stream deploys clean and then quietly buffers the whole response instead of streaming it.'
+  );
+}
+function encodeQuery(def) {
+  if (!def.name) throw new Error("query: `name` is required.");
+  if (!def.verb) throw new Error("query: `verb` is required.");
+  assertQueryPathParams(def);
+  assertQueryClosedSets(def);
+  warnUnboundReturn("query", def.name, def.stack, def.response);
+  const xdo = {
+    name: def.name,
+    description: def.description ?? "",
+    docs: def.docs ?? "",
+    api_enabled: def.apiEnabled ?? true,
+    auth: resolveAuth(def.name, def.auth),
+    response_type: def.responseType ?? "standard",
+    verb: def.verb,
+    disabled: def.disabled ?? false,
+    // The engine binds a query to its api group by the group's guid (export
+    // maps id→guid, import remaps guid→local id). Deriving that guid from the
+    // group's name is stateless and stable across syncs. A numeric `apiGroupId`
+    // is an explicit escape hatch and wins when given.
+    app: {
+      id: def.apiGroupId ?? (def.apiGroup !== void 0 ? resolveRef("app", def.apiGroup) : 0)
+    },
+    cache: defaultCache(def.cache),
+    output: [],
+    middleware: buildMiddlewareBlock(def.middleware),
+    tag: encodeTags(def.tags),
+    history: encodeHistory("query", def.history),
+    input: Object.entries(def.input ?? {}).map(([name, d]) => encodeInput(name, d)),
+    result: encodeResponse(def.response),
+    run: encodeStack("query", def.name, def.stack),
+    test: encodeTests(def.tests, "query", def.name),
+    example: encodeExample(def.example),
+    market_item: { id: 0, version: 0, guid: "" }
+  };
+  resolveMockKeys(xdo.run, xdo.test, "query", def.name);
+  return xdo;
+}
+function queryGuid(def) {
+  if (def.guid) return def.guid;
+  return deriveQueryGuid(queryGroupComponent(def), def.verb, def.name);
+}
+var queryKind = {
+  name: "query",
+  payloadKey: "query",
+  encode: encodeQuery,
+  guidOf: (def) => queryGuid(def)
+};
+registerKind(queryKind);
+function resolveCanonical(def, override) {
+  if (override) return override;
+  const group = def.apiGroup;
+  if (group && typeof group === "object" && typeof group.canonical === "string" && group.canonical !== "") {
+    return group.canonical;
+  }
+  const groupName = typeof group === "string" ? group : group?.name;
+  if (groupName) {
+    const locked = getLockedCanonical(lockKey("app", groupName));
+    if (locked) return locked;
+  }
+  throw new Error(
+    `query "${def.name}": getPath() cannot resolve the api group's canonical URL token. Set an explicit \`apiGroup({ canonical })\`, or run \`xanosdk export <entry>\` once (it mints a unique canonical and freezes it in xano.lock) and seed that lock before importing defs \u2014 the CLI does this automatically, and build scripts call seedLockOverrides(readLockFile(path)) first. As a last resort pass one directly: getPath({ canonical: "..." }). (Minting here is unsafe \u2014 canonicals must be unique per instance across all workspaces, so they are only generated at locked export.)`
+  );
+}
+function pathSegment(name) {
+  return name.replace(/^\/+/, "");
+}
+function queryImpl(def) {
+  if (typeof def.name !== "string") {
+    throw new Error(`query: \`name\` must be the route path as a string \u2014 got ${describeEntry(def.name)}.`);
+  }
+  const params = assertQueryPathParams(def);
+  assertQueryClosedSets(def);
+  const context = `query "${def.name}"`;
+  const path = pathSegment(def.name);
+  const getPath = (opts) => `/api:${resolveCanonical(def, opts?.canonical)}/${params.length ? fillPathParams(context, "getPath()", path, opts?.params, true) : path}`;
+  const search = (values) => toSearchParams(
+    // A non-record goes through whole, so it is refused as the free function refuses it.
+    params.length && isPlainRecord(values) ? Object.fromEntries(Object.entries(values).filter(([key]) => !params.includes(key))) : values
+  );
+  return { ...def, getPath, toSearchParams: search };
+}
+function isPlainRecord(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function toSearchParams(input) {
+  if (!isPlainRecord(input)) {
+    throw new Error(
+      `toSearchParams() takes the query input as a { name: value } record \u2014 got ${describeEntry(input)}.`
+    );
+  }
+  let params = new URLSearchParams();
+  const ancestors = [];
+  const fail = (path, why) => {
+    throw new TypeError(`toSearchParams: param "${path}" ${why}`);
+  };
+  const isScalar = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+  const encode = (path, value) => {
+    if (value == null) return false;
+    if (isScalar(value)) {
+      if (typeof value === "number" && !Number.isFinite(value)) fail(path, `is ${value} \u2014 not a finite value`);
+      params.append(path, String(value));
+      return true;
+    }
+    const proto = typeof value === "object" ? Object.getPrototypeOf(value) : 0;
+    if (path && !Array.isArray(value) && proto !== Object.prototype && proto !== null) {
+      fail(path, `is not a scalar, list or plain object (got ${describeEntry(value)})`);
+    }
+    if (ancestors.includes(value)) fail(path, "contains itself \u2014 a cycle has no query-string encoding");
+    ancestors.push(value);
+    let sent = false;
+    if (Array.isArray(value) && value.some(Array.isArray)) {
+      const outer = params;
+      params = new URLSearchParams();
+      value.forEach((item, index) => encode(`${path}[${index}]`, item));
+      params = outer;
+      params.append(path, JSON.stringify(value));
+      sent = true;
+    } else if (Array.isArray(value)) {
+      const plain = value.every(isScalar);
+      value.forEach((item, index) => {
+        if (!encode(`${path}[${plain ? "" : index}]`, item)) {
+          fail(`${path}[${index}]`, `is ${item == null ? item : "empty"}: a list item that sends nothing would move every later one up. Remove it, or give it a value`);
+        }
+        sent = true;
+      });
+    } else {
+      for (const [key, member] of Object.entries(value)) {
+        if (key === "" || /[[\]]/.test(key)) fail(path ? `${path}[${key}]` : key, "is empty or holds `[`/`]` \u2014 a query string cannot carry that name");
+        if (encode(path ? `${path}[${key}]` : key, member)) sent = true;
+      }
+    }
+    ancestors.pop();
+    return sent;
+  };
+  encode("", input);
+  return params;
+}
+var query = Object.assign(queryImpl, { toSearchParams });
+
+export {
+  warnUnboundReturn,
+  encodeResponse,
+  parsePathParams,
+  assertPathParamInputs,
+  unboundPathParams,
+  fillPathParams,
+  encodeTests,
+  test,
+  defaultCache,
+  encodeQuery,
+  queryKind,
+  pathSegment,
+  toSearchParams,
+  query
+};
+//# sourceMappingURL=chunk-6IUMKYWI.js.map

package/dist/chunk-6KEB3C3U.js

@@ -0,0 +1,65 @@
+// src/validate/runtime.ts
+async function smokeRunFunctions(client, workspaceId, names, inputs = {}, withInputs = /* @__PURE__ */ new Set()) {
+  const out = [];
+  for (const name of names) {
+    const res = await client.runFunction(workspaceId, name, inputs[name] ?? {});
+    const ran = res.ok && !threw(res.body);
+    const needsInputs = !ran && withInputs.has(name) && isInputError(res.body);
+    out.push({ name, ran, status: res.status, detail: res.body, ...needsInputs ? { needsInputs: true } : {} });
+  }
+  return out;
+}
+function functionsWithInputs(bundle) {
+  const fns = field(field(bundle, "payload"), "function");
+  const out = /* @__PURE__ */ new Set();
+  if (!Array.isArray(fns)) return out;
+  for (const fn of fns) {
+    const name = field(fn, "name");
+    const input = field(fn, "input");
+    if (typeof name === "string" && Array.isArray(input) && input.length > 0) out.add(name);
+  }
+  return out;
+}
+var INPUT_ERROR_CODE = "ERROR_CODE_INPUT_ERROR";
+function isInputError(body) {
+  const exception = field(field(body, "result"), "exception");
+  const codes = [field(body, "code"), field(exception, "error_type"), field(exception, "code")];
+  if (codes.includes(INPUT_ERROR_CODE)) return true;
+  return /\bMissing param\b/.test(runtimeErrorMessage(body) ?? "");
+}
+function threw(body) {
+  const result = body?.result;
+  const status = result?.status;
+  return typeof status === "string" && status !== "ok";
+}
+function runtimeErrorMessage(detail) {
+  const result = field(detail, "result");
+  const message = field(field(result, "exception"), "message") ?? field(detail, "message");
+  if (typeof message === "string" && message !== "") return message;
+  const thrown = field(field(result, "result"), "payload");
+  if (thrown === void 0) return void 0;
+  const store = field(result, "value_store") ?? field(detail, "value_store");
+  const value = typeof thrown === "string" && store !== null && typeof store === "object" && Object.hasOwn(store, thrown) ? store[thrown] : thrown;
+  if (value === void 0 || value === null || value === "") return void 0;
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+function describeRuntimeFailure(entry) {
+  const why = runtimeErrorMessage(entry.detail);
+  const requestFailed = entry.status < 200 || entry.status >= 300;
+  if (requestFailed) return `HTTP ${entry.status}${why !== void 0 ? `: ${why}` : ""}`;
+  if (why === void 0) return "threw";
+  const type = field(field(field(entry.detail, "result"), "exception"), "error_type");
+  const masked = type === "ERROR_CODE_BAD_REQUEST" && why === "Bad Request" || type === "ERROR_CODE_UNAUTHORIZED" && why === "Unauthorized";
+  return masked ? `threw ${why} \u2014 the run does not return the text of this error type` : `threw: ${why}`;
+}
+function field(v, key) {
+  return v !== null && typeof v === "object" ? v[key] : void 0;
+}
+
+export {
+  smokeRunFunctions,
+  functionsWithInputs,
+  runtimeErrorMessage,
+  describeRuntimeFailure
+};
+//# sourceMappingURL=chunk-6KEB3C3U.js.map