@pylonsync/sdk 0.4.6 → 0.4.8

package/dist/index.d.ts

@@ -403,16 +403,35 @@ export interface InputFieldDefinition {
 export interface QueryDefinition {
     name: string;
     input?: InputFieldDefinition[];
+    /**
+     * The function's declarative auth gate ("public" | "user" | …), as the
+     * router enforces it. Populated by `discoverFunctions()`; consumers
+     * (the OpenAPI generator) use it to mark which endpoints need
+     * credentials. Undefined means "not declared" — the runtime's default
+     * is "user".
+     */
+    auth?: string;
 }
 export declare function query(name: string, options?: {
     input?: InputFieldDefinition[];
+    auth?: string;
 }): QueryDefinition;
 export interface ActionDefinition {
     name: string;
     input?: InputFieldDefinition[];
+    /** See `QueryDefinition.auth`. */
+    auth?: string;
+    /**
+     * Which write kind this was before the manifest's read/write split
+     * collapsed mutations and actions into one bucket. Preserved so a
+     * generated spec can tell them apart.
+     */
+    fnType?: "mutation" | "action";
 }
 export declare function action(name: string, options?: {
     input?: InputFieldDefinition[];
+    auth?: string;
+    fnType?: "mutation" | "action";
 }): ActionDefinition;
 export interface PolicyDefinition {
     /** Optional — `buildManifest` auto-generates a name from the entity
@@ -568,10 +587,16 @@ export interface ManifestInputField {
 export interface ManifestQuery {
     name: string;
     input?: ManifestInputField[];
+    /** Declarative auth gate as the router enforces it. Absent → "user". */
+    auth?: string;
 }
 export interface ManifestAction {
     name: string;
     input?: ManifestInputField[];
+    /** Declarative auth gate as the router enforces it. Absent → "user". */
+    auth?: string;
+    /** "mutation" or "action" — the manifest bucket holds both. */
+    fn_type?: string;
 }
 export interface ManifestPolicy {
     name: string;
@@ -739,6 +764,44 @@ export declare function routesToManifest(routes: RouteDefinition[]): ManifestRou
 export declare function discoverAppRoutes(opts?: {
     appDir?: string;
 }): Promise<RouteDefinition[]>;
+export interface DiscoveredFunctions {
+    queries: QueryDefinition[];
+    actions: ActionDefinition[];
+}
+/**
+ * Walk `functions/` and return every externally callable function, for
+ * `buildManifest({ queries, actions })`.
+ *
+ * The counterpart to `discoverAppRoutes()`. Without it, `buildManifest`
+ * takes `queries`/`actions` that nothing produces, so apps ship
+ * manifests describing zero callable endpoints while `/api/fn/<name>`
+ * serves dozens — `/api/manifest`, the generated OpenAPI spec, and
+ * `pylon codegen` all under-report in the same silent way.
+ *
+ * Discovery deliberately mirrors the runtime loader
+ * (`packages/functions/src/runtime.ts`) exactly: top-level `.ts`/`.js`
+ * files in `functions/`, no recursion, name = basename without the
+ * extension, and a default export whose `type` is a string and whose
+ * `handler` is a function. Anything the runtime would not register does
+ * not appear here, and vice versa — a manifest that disagrees with the
+ * router describes endpoints that don't exist.
+ *
+ * `internal: true` functions are excluded: the router refuses external
+ * calls to them with `FN_NOT_FOUND`, so listing them would document
+ * endpoints no client can reach.
+ *
+ * Queries go to `queries`; mutations and actions both go to `actions`,
+ * because the manifest's split is read vs write and has no third bucket.
+ * `fnType` on the entry preserves which one it was.
+ *
+ * Each file is dynamically imported, so function modules must be free of
+ * side effects at import time. That is already true of any module the
+ * runtime loads — this runs the same imports the server does — but it is
+ * a contract worth knowing about.
+ */
+export declare function discoverFunctions(opts?: {
+    fnDir?: string;
+}): Promise<DiscoveredFunctions>;
 export declare function queriesToManifest(queries: QueryDefinition[]): ManifestQuery[];
 export declare function actionsToManifest(actions: ActionDefinition[]): ManifestAction[];
 export declare function policiesToManifest(policies: PolicyDefinition[]): ManifestPolicy[];

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.6",
+  "version": "0.4.8",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/function-discovery.test.ts

@@ -0,0 +1,207 @@
+// Function discovery (discoverFunctions) — the functions/ walk that fills
+// buildManifest's queries/actions. The correctness bar is agreement with the
+// runtime loader in packages/functions/src/runtime.ts: a manifest that lists
+// something the router won't serve documents an endpoint that doesn't exist,
+// and one that omits a live function under-reports the whole API.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { discoverFunctions } from "./index";
+
+describe("discoverFunctions", () => {
+  const tmpdirs: string[] = [];
+  const prevCwd = process.cwd();
+  afterEach(() => {
+    process.chdir(prevCwd);
+    for (const d of tmpdirs.splice(0)) {
+      try {
+        fs.rmSync(d, { recursive: true, force: true });
+      } catch {
+        /* best effort */
+      }
+    }
+  });
+
+  /** Materialize a functions/ dir (filename → module source) and chdir in. */
+  function fns(files: Record<string, string>): void {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-fns-"));
+    tmpdirs.push(root);
+    for (const [rel, src] of Object.entries(files)) {
+      const abs = path.join(root, "functions", rel);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, src);
+    }
+    process.chdir(root);
+  }
+
+  /**
+   * A function module shaped like `@pylonsync/functions` builds one. Written
+   * literally rather than imported so the SDK's test suite doesn't take a
+   * dependency on the functions package.
+   */
+  const fn = (
+    type: string,
+    args: string = "{}",
+    extra: string = "",
+  ): string =>
+    `export default { type: ${JSON.stringify(type)}, handler: () => null, args: ${args}${extra} };`;
+
+  test("splits queries from writes", async () => {
+    fns({
+      "listEvents.ts": fn("query"),
+      "saveEvent.ts": fn("mutation"),
+      "sendInvite.ts": fn("action"),
+    });
+    const { queries, actions } = await discoverFunctions();
+    expect(queries.map((q) => q.name)).toEqual(["listEvents"]);
+    // Mutations and actions share the write bucket; fnType keeps them apart.
+    expect(actions.map((a) => a.name).sort()).toEqual([
+      "saveEvent",
+      "sendInvite",
+    ]);
+    expect(actions.find((a) => a.name === "saveEvent")!.fnType).toBe("mutation");
+    expect(actions.find((a) => a.name === "sendInvite")!.fnType).toBe("action");
+  });
+
+  test("excludes internal functions", async () => {
+    // The router answers FN_NOT_FOUND for these, so listing one would
+    // document an endpoint no external client can reach.
+    fns({
+      "publicOne.ts": fn("query"),
+      "secretOne.ts": fn("query", "{}", ", internal: true"),
+    });
+    const { queries } = await discoverFunctions();
+    expect(queries.map((q) => q.name)).toEqual(["publicOne"]);
+  });
+
+  test("maps validators onto manifest field types", async () => {
+    fns({
+      "saveTrack.ts": fn(
+        "mutation",
+        `{
+          title: { type: "string" },
+          seats: { type: "int" },
+          price: { type: "float" },
+          live: { type: "bool" },
+          startsAt: { type: "datetime" },
+          eventId: { type: "id", table: "Event" }
+        }`,
+      ),
+    });
+    const { actions } = await discoverFunctions();
+    const byName = Object.fromEntries(
+      actions[0]!.input!.map((f) => [f.name, f.type]),
+    );
+    expect(byName).toEqual({
+      title: "string",
+      seats: "int",
+      price: "float",
+      live: "bool",
+      startsAt: "datetime",
+      eventId: "id(Event)",
+    });
+  });
+
+  test("reads optional off the validator and keeps the id table", async () => {
+    // v.optional(v.id("Event")) spreads the inner validator and adds
+    // optional:true, so `table` survives the wrapper.
+    fns({
+      "attach.ts": fn(
+        "mutation",
+        `{
+          eventId: { type: "id", table: "Event", optional: true },
+          note: { type: "string" }
+        }`,
+      ),
+    });
+    const { actions } = await discoverFunctions();
+    const input = actions[0]!.input!;
+    const eventId = input.find((f) => f.name === "eventId")!;
+    expect(eventId.optional).toBe(true);
+    expect(eventId.type).toBe("id(Event)");
+    expect(input.find((f) => f.name === "note")!.optional).toBe(false);
+  });
+
+  test("unmapped validators collapse to json", async () => {
+    // FieldType has no array or union variant. Documented lossiness —
+    // widening FieldType is what would preserve Validator.items.
+    fns({
+      "bulk.ts": fn(
+        "action",
+        `{
+          tags: { type: "array", items: { type: "string" } },
+          payload: { type: "any" },
+          blob: { type: "json" }
+        }`,
+      ),
+    });
+    const { actions } = await discoverFunctions();
+    for (const field of actions[0]!.input!) {
+      expect(field.type).toBe("json");
+    }
+  });
+
+  test("carries the declared auth gate", async () => {
+    fns({
+      "publicFeed.ts": fn("query", "{}", `, auth: "public"`),
+      "myProfile.ts": fn("query"),
+    });
+    const { queries } = await discoverFunctions();
+    expect(queries.find((q) => q.name === "publicFeed")!.auth).toBe("public");
+    // Undeclared stays undefined rather than being invented — the
+    // runtime's default is "user" and consumers apply it.
+    expect(queries.find((q) => q.name === "myProfile")!.auth).toBeUndefined();
+  });
+
+  test("skips modules whose default export is not a function definition", async () => {
+    fns({
+      "real.ts": fn("query"),
+      "config.ts": "export default { apiKey: 'x' };",
+      "noDefault.ts": "export const helper = () => null;",
+      // `type` present but no handler — the runtime's shape check
+      // rejects this too.
+      "halfBaked.ts": "export default { type: 'query' };",
+    });
+    const { queries, actions } = await discoverFunctions();
+    expect(queries.map((q) => q.name)).toEqual(["real"]);
+    expect(actions).toEqual([]);
+  });
+
+  test("a module that throws on import is skipped, not fatal", async () => {
+    fns({
+      "good.ts": fn("query"),
+      "explodes.ts": "throw new Error('boom');",
+    });
+    const { queries } = await discoverFunctions();
+    expect(queries.map((q) => q.name)).toEqual(["good"]);
+  });
+
+  test("no functions directory yields empty, not an error", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-fns-"));
+    tmpdirs.push(root);
+    process.chdir(root);
+    expect(await discoverFunctions()).toEqual({ queries: [], actions: [] });
+  });
+
+  test("output is sorted so two machines agree", async () => {
+    fns({
+      "zebra.ts": fn("query"),
+      "alpha.ts": fn("query"),
+      "middle.ts": fn("query"),
+    });
+    const { queries } = await discoverFunctions();
+    expect(queries.map((q) => q.name)).toEqual(["alpha", "middle", "zebra"]);
+  });
+
+  test("ignores non-module files the runtime would also ignore", async () => {
+    fns({
+      "real.ts": fn("query"),
+      "notes.md": "# not a function",
+      "data.json": "{}",
+    });
+    const { queries } = await discoverFunctions();
+    expect(queries.map((q) => q.name)).toEqual(["real"]);
+  });
+});

package/src/index.ts

@@ -532,13 +532,21 @@ export interface InputFieldDefinition {
 export interface QueryDefinition {
   name: string;
   input?: InputFieldDefinition[];
+  /**
+   * The function's declarative auth gate ("public" | "user" | …), as the
+   * router enforces it. Populated by `discoverFunctions()`; consumers
+   * (the OpenAPI generator) use it to mark which endpoints need
+   * credentials. Undefined means "not declared" — the runtime's default
+   * is "user".
+   */
+  auth?: string;
 }
 
 export function query(
   name: string,
-  options?: { input?: InputFieldDefinition[] }
+  options?: { input?: InputFieldDefinition[]; auth?: string }
 ): QueryDefinition {
-  return { name, input: options?.input };
+  return { name, input: options?.input, auth: options?.auth };
 }
 
 // ---------------------------------------------------------------------------
@@ -548,13 +556,30 @@ export function query(
 export interface ActionDefinition {
   name: string;
   input?: InputFieldDefinition[];
+  /** See `QueryDefinition.auth`. */
+  auth?: string;
+  /**
+   * Which write kind this was before the manifest's read/write split
+   * collapsed mutations and actions into one bucket. Preserved so a
+   * generated spec can tell them apart.
+   */
+  fnType?: "mutation" | "action";
 }
 
 export function action(
   name: string,
-  options?: { input?: InputFieldDefinition[] }
+  options?: {
+    input?: InputFieldDefinition[];
+    auth?: string;
+    fnType?: "mutation" | "action";
+  }
 ): ActionDefinition {
-  return { name, input: options?.input };
+  return {
+    name,
+    input: options?.input,
+    auth: options?.auth,
+    fnType: options?.fnType,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -745,11 +770,17 @@ export interface ManifestInputField {
 export interface ManifestQuery {
   name: string;
   input?: ManifestInputField[];
+  /** Declarative auth gate as the router enforces it. Absent → "user". */
+  auth?: string;
 }
 
 export interface ManifestAction {
   name: string;
   input?: ManifestInputField[];
+  /** Declarative auth gate as the router enforces it. Absent → "user". */
+  auth?: string;
+  /** "mutation" or "action" — the manifest bucket holds both. */
+  fn_type?: string;
 }
 
 export interface ManifestPolicy {
@@ -1322,6 +1353,190 @@ export async function discoverAppRoutes(opts?: {
   return [...navigable, ...boundaryRoutes];
 }
 
+// ---------------------------------------------------------------------------
+// Function discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * A function definition as `@pylonsync/functions` builds it. Structural —
+ * the SDK does not depend on that package (it would drag server-only
+ * modules into client bundles), so this mirrors the shape the runtime
+ * loader checks for.
+ */
+interface RuntimeFnDefinition {
+  type: "query" | "mutation" | "action";
+  handler: unknown;
+  args?: Record<string, RuntimeValidator>;
+  internal?: boolean;
+  auth?: string;
+}
+
+/** A `v.*` validator: `{type, optional?, table?, items?}`. */
+interface RuntimeValidator {
+  type: string;
+  optional?: boolean;
+  table?: string;
+}
+
+/**
+ * Map a validator onto the manifest's field type.
+ *
+ * `FieldType` has no array or union variant, so `v.array(...)`,
+ * `v.union(...)`, and `v.any()` all land on `json`. The element type in
+ * `Validator.items` is information this boundary throws away — widening
+ * `FieldType` is the fix, and it would materially improve a generated
+ * OpenAPI spec.
+ */
+function validatorToFieldType(validator: RuntimeValidator): FieldType {
+  switch (validator.type) {
+    case "string":
+      return "string";
+    case "int":
+      return "int";
+    case "float":
+    case "number":
+      return "float";
+    case "bool":
+    case "boolean":
+      return "bool";
+    case "datetime":
+      return "datetime";
+    case "id":
+      // `v.optional(v.id("Event"))` spreads the inner validator, so
+      // `table` survives the optional wrapper.
+      return validator.table ? (`id(${validator.table})` as FieldType) : "string";
+    default:
+      return "json";
+  }
+}
+
+function argsToInput(
+  args: Record<string, RuntimeValidator> | undefined
+): InputFieldDefinition[] {
+  if (!args) return [];
+  return Object.entries(args).map(([name, validator]) => ({
+    name,
+    type: validatorToFieldType(validator),
+    // `v.optional(inner)` sets `optional: true` on the spread validator
+    // itself, so this reads correctly without unwrapping.
+    optional: validator.optional === true,
+  }));
+}
+
+export interface DiscoveredFunctions {
+  queries: QueryDefinition[];
+  actions: ActionDefinition[];
+}
+
+/**
+ * Walk `functions/` and return every externally callable function, for
+ * `buildManifest({ queries, actions })`.
+ *
+ * The counterpart to `discoverAppRoutes()`. Without it, `buildManifest`
+ * takes `queries`/`actions` that nothing produces, so apps ship
+ * manifests describing zero callable endpoints while `/api/fn/<name>`
+ * serves dozens — `/api/manifest`, the generated OpenAPI spec, and
+ * `pylon codegen` all under-report in the same silent way.
+ *
+ * Discovery deliberately mirrors the runtime loader
+ * (`packages/functions/src/runtime.ts`) exactly: top-level `.ts`/`.js`
+ * files in `functions/`, no recursion, name = basename without the
+ * extension, and a default export whose `type` is a string and whose
+ * `handler` is a function. Anything the runtime would not register does
+ * not appear here, and vice versa — a manifest that disagrees with the
+ * router describes endpoints that don't exist.
+ *
+ * `internal: true` functions are excluded: the router refuses external
+ * calls to them with `FN_NOT_FOUND`, so listing them would document
+ * endpoints no client can reach.
+ *
+ * Queries go to `queries`; mutations and actions both go to `actions`,
+ * because the manifest's split is read vs write and has no third bucket.
+ * `fnType` on the entry preserves which one it was.
+ *
+ * Each file is dynamically imported, so function modules must be free of
+ * side effects at import time. That is already true of any module the
+ * runtime loads — this runs the same imports the server does — but it is
+ * a contract worth knowing about.
+ */
+export async function discoverFunctions(opts?: {
+  fnDir?: string;
+}): Promise<DiscoveredFunctions> {
+  // Same lazy node-builtin resolution as discoverAppRoutes: the SDK
+  // carries no @types/node and must stay importable from client code.
+  let fs: any;
+  let path: any;
+  let url: any;
+  try {
+    const nodeReq =
+      (globalThis as any).require ??
+      (await import("node:module")).createRequire(import.meta.url);
+    fs = nodeReq("node:fs");
+    path = nodeReq("node:path");
+    url = nodeReq("node:url");
+  } catch {
+    return { queries: [], actions: [] };
+  }
+  if (!fs || !path || !url) return { queries: [], actions: [] };
+
+  const cwd = (globalThis as any).process?.cwd?.() ?? ".";
+  const fnDir =
+    opts?.fnDir && path.isAbsolute(opts.fnDir)
+      ? opts.fnDir
+      : path.join(cwd, opts?.fnDir ?? "functions");
+  if (!fs.existsSync(fnDir) || !fs.statSync(fnDir).isDirectory()) {
+    return { queries: [], actions: [] };
+  }
+
+  const files: string[] = fs
+    .readdirSync(fnDir)
+    .filter((f: string) => f.endsWith(".ts") || f.endsWith(".js"))
+    // Sorted so two machines produce byte-identical manifests.
+    .sort();
+
+  const queries: QueryDefinition[] = [];
+  const actions: ActionDefinition[] = [];
+
+  for (const file of files) {
+    const name = file.replace(/\.(ts|js)$/, "");
+    let definition: RuntimeFnDefinition | undefined;
+    try {
+      const mod = await import(
+        url.pathToFileURL(path.join(fnDir, file)).href
+      );
+      definition = mod?.default as RuntimeFnDefinition | undefined;
+    } catch {
+      // A module that won't import can't be serving traffic either.
+      // The runtime loader logs and skips; so do we, rather than
+      // failing the whole manifest build over one bad file.
+      continue;
+    }
+
+    // The runtime's own registration check. A default export that isn't
+    // a function definition (a config object, a React component in the
+    // wrong directory) is silently skipped there and here.
+    const shape = definition as unknown as Record<string, unknown> | undefined;
+    if (
+      !shape ||
+      typeof shape.type !== "string" ||
+      typeof shape.handler !== "function"
+    ) {
+      continue;
+    }
+    if (shape.internal === true) continue;
+
+    const input = argsToInput(definition!.args);
+    const auth = typeof shape.auth === "string" ? shape.auth : undefined;
+    if (definition!.type === "query") {
+      queries.push({ name, input, auth });
+    } else {
+      actions.push({ name, input, auth, fnType: definition!.type });
+    }
+  }
+
+  return { queries, actions };
+}
+
 export function queriesToManifest(queries: QueryDefinition[]): ManifestQuery[] {
   return queries.map((q) => {
     const result: ManifestQuery = { name: q.name };
@@ -1333,6 +1548,7 @@ export function queriesToManifest(queries: QueryDefinition[]): ManifestQuery[] {
         unique: false as const,
       }));
     }
+    if (q.auth) result.auth = q.auth;
     return result;
   });
 }
@@ -1350,6 +1566,8 @@ export function actionsToManifest(
         unique: false as const,
       }));
     }
+    if (a.auth) result.auth = a.auth;
+    if (a.fnType) result.fn_type = a.fnType;
     return result;
   });
 }