@pylonsync/functions 0.22.32 → 0.22.34

package/dist/runtime.d.ts

@@ -14,7 +14,7 @@
  *   each ctx.db / ctx.scheduler / ctx.runMutation call), so the map never
  *   needs to queue multiple RPCs per call_id.
  */
-import type { DbReader, DbWriter, Llm, Rooms, Workflows, Audit } from "./types";
+import type { DbReader, DbWriter, Llm, Rooms, Workflows, Audit, ApiKeys } from "./types";
 export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
 export declare function buildSsrFnCaller(callId: string): (name: string, args?: Record<string, unknown>) => Promise<unknown>;
 export declare function buildDbWriter(callId: string): DbWriter;
@@ -48,4 +48,6 @@ export declare function buildRooms(callId: string): Rooms;
  */
 /** Build `ctx.audit` — round-trips `audit_op` frames to the host. */
 export declare function buildAudit(callId: string): Audit;
+/** Build `ctx.apiKeys` — round-trips `api_key_op` frames to the host. */
+export declare function buildApiKeys(callId: string): ApiKeys;
 export declare function buildWorkflows(callId: string): Workflows;

package/dist/types.d.ts

@@ -628,6 +628,46 @@ export interface AuditLog {
         id: string;
     }>;
 }
+/**
+ * `ctx.apiKeys`: API keys for the app's own users, minted from server
+ * code. For a service user the app runs (for example one per AI agent),
+ * where the HTTP route `POST /api/auth/api-keys` does not fit because it
+ * mints a key for the signed-in caller only.
+ *
+ * Actions only. The action must be `internal: true` or have called
+ * `ctx.auth.elevate({ admin: true, reason })` after checking its own
+ * caller; anything else is refused with `API_KEYS_FORBIDDEN`. Not in
+ * mutations: a key is not part of the mutation's transaction.
+ * Every call is in the server log with the function name and user id.
+ */
+export interface ApiKeys {
+    /**
+     * Mint a key for `userId`. The plaintext `key` is returned once and is
+     * never readable again; store it where the key's holder can use it.
+     * `expiresAt` is unix seconds. `name` is a label (at most 100
+     * characters).
+     */
+    create(options: {
+        userId: string;
+        name?: string;
+        expiresAt?: number;
+    }): Promise<{
+        key: string;
+        id: string;
+        prefix: string;
+        expiresAt: number | null;
+    }>;
+    /**
+     * Revoke key `keyId` of `userId`. `revoked` is false when no key of
+     * that user has that id.
+     */
+    revoke(options: {
+        userId: string;
+        keyId: string;
+    }): Promise<{
+        revoked: boolean;
+    }>;
+}
 /**
  * `ctx.audit` on actions: {@link AuditLog.log} plus reads. Mutations get
  * only `log`: in a Postgres mutation the transaction holds a connection,
@@ -1371,6 +1411,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     workflows: Workflows;
     /** Application audit log — see {@link Audit}. */
     audit: Audit;
+    /** API keys for the app's own users, from server code — see {@link ApiKeys}. */
+    apiKeys: ApiKeys;
     /** Run an `agent()` as a named user from server code — see {@link Agents}. */
     agents: Agents;
     /** Attach / register custom domains for your app's OWN end-customers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.22.32",
+  "version": "0.22.34",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/runtime.ts

@@ -39,6 +39,7 @@ import type {
   WorkflowRunSummary,
   Audit,
   AuditEntry,
+  ApiKeys,
   Connections,
   Domains,
   TenantDomainResult,
@@ -1102,6 +1103,37 @@ export function buildAudit(callId: string): Audit {
   };
 }
 
+/** Build `ctx.apiKeys` — round-trips `api_key_op` frames to the host. */
+export function buildApiKeys(callId: string): ApiKeys {
+  return {
+    async create(options) {
+      // A value Rust cannot read as u64 would be dropped by the host and
+      // leave the call waiting; NaN would turn into "never expires".
+      const exp = options.expiresAt;
+      if (exp !== undefined && !(Number.isSafeInteger(exp) && exp >= 0)) {
+        const err = new Error("ctx.apiKeys.create expiresAt must be a whole number of unix seconds, 0 or more");
+        (err as { code?: string }).code = "INVALID_ARGS";
+        throw err;
+      }
+      return (await rpc(callId, {
+        type: "api_key_op",
+        op: "create",
+        user_id: options.userId,
+        name: options.name ?? null,
+        expires_at: options.expiresAt ?? null,
+      })) as { key: string; id: string; prefix: string; expiresAt: number | null };
+    },
+    async revoke(options) {
+      return (await rpc(callId, {
+        type: "api_key_op",
+        op: "revoke",
+        user_id: options.userId,
+        key_id: options.keyId,
+      })) as { revoked: boolean };
+    },
+  };
+}
+
 export function buildWorkflows(callId: string): Workflows {
   return {
     async start(name: string, input?: unknown, opts?: { key?: string }) {
@@ -1356,6 +1388,7 @@ function buildActionCtx(
     connections,
     workflows: buildWorkflows(callId),
     audit: buildAudit(callId),
+    apiKeys: buildApiKeys(callId),
     agents: {
       async run(name, options) {
         if (!options || typeof options.as?.userId !== "string") {

package/src/ssr-client-bundler.test.ts

@@ -804,3 +804,14 @@ describe("nearestBoundaryComponent across route groups", () => {
     ).toBe("app/(marketing)/not-found");
   });
 });
+
+describe("client router popstate", () => {
+  test("a hash-only popstate does not re-render the route", () => {
+    // Clicking a same-page anchor fires popstate. Treating it as a navigation
+    // re-rendered the page and scrolled back to the top.
+    const src = fs.readFileSync(path.join(import.meta.dir, "ssr-client-bundler.ts"), "utf8");
+    const popstate = src.slice(src.indexOf('window.addEventListener("popstate"'));
+    expect(popstate).toContain("if (next === renderedPath) return;");
+    expect(src.match(/renderedPath = location\.pathname \+ location\.search;/g)?.length).toBeGreaterThanOrEqual(3);
+  });
+});

package/src/ssr-client-bundler.ts

@@ -830,6 +830,12 @@ function renderPendingPlaceholder(pathname, manifest, myEpoch) {
   return true;
 }
 
+// The path and query the page last rendered. A popstate that keeps them and
+// only changes the hash is a same-page jump (an anchor link, a back press
+// between anchors), not a navigation: re-rendering for it would reset the
+// scroll to the top.
+let renderedPath = "";
+
 async function navigate(href, opts) {
   const push = !opts || opts.push !== false;
   const url = new URL(href, location.href);
@@ -891,6 +897,7 @@ async function navigate(href, opts) {
           history.pushState({ component: matched.component }, "", target);
         }
         window.dispatchEvent(new Event("pylon:navigation"));
+        renderedPath = location.pathname + location.search;
         window.scrollTo(0, 0);
         didOptimistic = true;
       }
@@ -915,6 +922,7 @@ async function navigate(href, opts) {
       loadManifest().then((manifest) => {
         if (navState.settled || myEpoch !== navEpoch) return;
         if (renderPendingPlaceholder(url.pathname, manifest, myEpoch)) {
+          renderedPath = location.pathname + location.search;
           window.scrollTo(0, 0);
         }
       });
@@ -1013,6 +1021,7 @@ async function navigate(href, opts) {
     // re-read location after a Link click or a router.push(). popstate already
     // covers back/forward, but pushState/replaceState fire no event.
     window.dispatchEvent(new Event("pylon:navigation"));
+    renderedPath = location.pathname + location.search;
     // After a successful nav, scroll to top (Next.js default).
     window.scrollTo(0, 0);
   }
@@ -1042,8 +1051,11 @@ function installNavHandlers() {
     const seed = seeds ? seeds.get(link) : undefined;
     navigate(href, seed != null ? { seed } : undefined);
   });
+  renderedPath = location.pathname + location.search;
   window.addEventListener("popstate", () => {
-    navigate(location.pathname + location.search, { push: false });
+    const next = location.pathname + location.search;
+    if (next === renderedPath) return;
+    navigate(next, { push: false });
   });
   // Progressive-enhancement form submit (#276): intercept <form data-pylon-form>
   // so the page doesn't full-reload. fetch the same route.ts endpoint, follow

package/src/types.ts

@@ -705,6 +705,37 @@ export interface AuditLog {
   }): Promise<{ id: string }>;
 }
 
+/**
+ * `ctx.apiKeys`: API keys for the app's own users, minted from server
+ * code. For a service user the app runs (for example one per AI agent),
+ * where the HTTP route `POST /api/auth/api-keys` does not fit because it
+ * mints a key for the signed-in caller only.
+ *
+ * Actions only. The action must be `internal: true` or have called
+ * `ctx.auth.elevate({ admin: true, reason })` after checking its own
+ * caller; anything else is refused with `API_KEYS_FORBIDDEN`. Not in
+ * mutations: a key is not part of the mutation's transaction.
+ * Every call is in the server log with the function name and user id.
+ */
+export interface ApiKeys {
+  /**
+   * Mint a key for `userId`. The plaintext `key` is returned once and is
+   * never readable again; store it where the key's holder can use it.
+   * `expiresAt` is unix seconds. `name` is a label (at most 100
+   * characters).
+   */
+  create(options: {
+    userId: string;
+    name?: string;
+    expiresAt?: number;
+  }): Promise<{ key: string; id: string; prefix: string; expiresAt: number | null }>;
+  /**
+   * Revoke key `keyId` of `userId`. `revoked` is false when no key of
+   * that user has that id.
+   */
+  revoke(options: { userId: string; keyId: string }): Promise<{ revoked: boolean }>;
+}
+
 /**
  * `ctx.audit` on actions: {@link AuditLog.log} plus reads. Mutations get
  * only `log`: in a Postgres mutation the transaction holds a connection,
@@ -1500,6 +1531,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   workflows: Workflows;
   /** Application audit log — see {@link Audit}. */
   audit: Audit;
+  /** API keys for the app's own users, from server code — see {@link ApiKeys}. */
+  apiKeys: ApiKeys;
   /** Run an `agent()` as a named user from server code — see {@link Agents}. */
   agents: Agents;
   /** Attach / register custom domains for your app's OWN end-customers