zuplo 6.69.6 → 6.69.8

package/docs/dev-portal/zudoku/extending/hooks.md

@@ -0,0 +1,243 @@
+---
+title: Hooks
+sidebar_icon: webhook
+description: Reference for the React hooks exported by Zudoku.
+---
+
+Dev Portal exposes a set of React hooks that let you read and interact with the runtime state of your
+site from custom components, MDX pages, plugins, and [slots](../configuration/slots.mdx). All hooks
+are available from the `zudoku/hooks` entry point.
+
+```typescript
+import {
+  useAuth,
+  useVerifiedEmail,
+  useRefreshUserProfile,
+  useZudoku,
+  useCache,
+  useEvent,
+  useExposedProps,
+  useTheme,
+  useMDXComponents,
+} from "zudoku/hooks";
+```
+
+## `useAuth`
+
+The `useAuth` hook is the primary way to interact with authentication in Zudoku. It returns the
+current auth state along with the actions needed to sign users in and out. It works with any of the
+supported [authentication providers](../configuration/authentication.md).
+
+```typescript
+import { useAuth } from "zudoku/hooks";
+
+const { isAuthEnabled, isAuthenticated, isPending, profile, login, logout, signup } = useAuth();
+```
+
+### Returned values
+
+| Property          | Type                                             | Description                                                                                                                            |
+| ----------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `isAuthEnabled`   | `boolean`                                        | `true` if an `authentication` provider is configured in `zudoku.config.ts`. When `false`, the action methods will throw if called.     |
+| `isAuthenticated` | `boolean`                                        | Whether a user is currently signed in.                                                                                                 |
+| `isPending`       | `boolean`                                        | `true` while the provider is still initializing or restoring a session. Use this to render loading states and avoid flashing UI.       |
+| `profile`         | `UserProfile \| null`                            | The authenticated user's profile, or `null` when signed out. See [User profile](#user-profile).                                        |
+| `providerData`    | `ProviderData \| null`                           | Raw provider-specific data (for example the Supabase session or Firebase user). Useful when you need access to provider-only features. |
+| `login`           | `(options?: AuthActionOptions) => Promise<void>` | Starts the sign-in flow. Redirects back to the current page by default.                                                                |
+| `logout`          | `() => Promise<void>`                            | Signs the user out.                                                                                                                    |
+| `signup`          | `(options?: AuthActionOptions) => Promise<void>` | Starts the sign-up flow, if the provider supports it. Redirects back to the current page by default.                                   |
+
+`AuthActionOptions` accepts:
+
+```typescript
+type AuthActionOptions = {
+  /** URL to redirect to after the action completes. Defaults to the current page. */
+  redirectTo?: string;
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+};
+```
+
+### User profile
+
+When `isAuthenticated` is `true`, `profile` is populated with the fields returned by the provider's
+user info endpoint:
+
+```typescript
+type UserProfile = {
+  sub: string;
+  email: string | undefined;
+  emailVerified: boolean;
+  name: string | undefined;
+  pictureUrl: string | undefined;
+  // Any additional claims returned by the provider
+  [key: string]: string | boolean | undefined;
+};
+```
+
+### Example: sign-in button
+
+```tsx
+import { useAuth } from "zudoku/hooks";
+import { Button } from "zudoku/ui/Button.js";
+
+export const AuthButton = () => {
+  const { isAuthenticated, isPending, profile, login, logout } = useAuth();
+
+  if (isPending) {
+    return <Button disabled>Loading…</Button>;
+  }
+
+  if (!isAuthenticated) {
+    return <Button onClick={() => login()}>Sign in</Button>;
+  }
+
+  return (
+    <div className="flex items-center gap-2">
+      <span>Hi, {profile?.name ?? profile?.email}</span>
+      <Button onClick={() => logout()}>Sign out</Button>
+    </div>
+  );
+};
+```
+
+### Example: gating content
+
+```tsx
+import { useAuth } from "zudoku/hooks";
+
+export const PremiumContent = ({ children }: { children: React.ReactNode }) => {
+  const { isAuthenticated, isPending, login } = useAuth();
+
+  if (isPending) return null;
+
+  if (!isAuthenticated) {
+    return (
+      <button type="button" onClick={() => login({ redirectTo: window.location.href })}>
+        Sign in to view this content
+      </button>
+    );
+  }
+
+  return <>{children}</>;
+};
+```
+
+For route-level gating, prefer the declarative
+[protected routes](../configuration/protected-routes.md) configuration.
+
+## `useVerifiedEmail`
+
+Returns the current user's email verification state and exposes helpers to refresh it or request a
+new verification email. Use this in components that show verification banners or block actions until
+the user has verified their address.
+
+```typescript
+import { useVerifiedEmail } from "zudoku/hooks";
+
+const { email, isVerified, supportsEmailVerification, refresh, requestEmailVerification } =
+  useVerifiedEmail();
+```
+
+| Property                    | Type                                             | Description                                                                                                                |
+| --------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `email`                     | `string \| undefined`                            | The user's email address, if any.                                                                                          |
+| `isVerified`                | `boolean \| undefined`                           | Whether the provider reports the email as verified. `undefined` when no profile is available (e.g. signed out or pending). |
+| `supportsEmailVerification` | `boolean`                                        | `true` when the provider implements a `requestEmailVerification` method.                                                   |
+| `refresh`                   | `() => void`                                     | Re-fetch the user profile from the provider — useful after the user verifies in another tab.                               |
+| `requestEmailVerification`  | `(options?: AuthActionOptions) => Promise<void>` | Triggers the provider's "resend verification email" flow.                                                                  |
+
+The hook automatically refreshes the profile when the window regains focus so `isVerified` updates
+after the user completes verification elsewhere.
+
+## `useRefreshUserProfile`
+
+Low-level hook that re-fetches the authenticated user's profile from the configured provider. Most
+applications do not need to call this directly — `useAuth` already invokes it, and
+`useVerifiedEmail` exposes a more ergonomic `refresh()`. Reach for it when you need fine-grained
+control over the underlying React Query.
+
+```typescript
+import { useRefreshUserProfile } from "zudoku/hooks";
+
+const { refetch, isFetching } = useRefreshUserProfile({ refetchOnWindowFocus: "always" });
+```
+
+It returns the full
+[React Query `UseQueryResult`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery).
+
+## `useZudoku`
+
+Returns the global [`ZudokuContext`](../custom-plugins.md) — the object that holds navigation, auth,
+plugins, the React Query client, and user-configured options. Use it when you need access to app
+configuration that isn't exposed by a more specific hook.
+
+```typescript
+import { useZudoku } from "zudoku/hooks";
+
+const { options, navigation, queryClient, addEventListener, emitEvent } = useZudoku();
+```
+
+Must be called inside the `ZudokuProvider` (i.e. inside any Dev Portal page or slot). Calling it outside
+throws.
+
+## `useEvent`
+
+Subscribes to Dev Portal events (such as navigation or authentication changes) with automatic cleanup.
+See the [Events](./events.md) page for the full guide and the list of available events.
+
+```typescript
+import { useEvent } from "zudoku/hooks";
+
+// Access the latest event payload. When called without a callback, useEvent
+// returns the event's argument tuple — destructure it to get the payload.
+const [locationEvent] = useEvent("location") ?? [];
+
+// Or transform the payload with a callback
+const pathname = useEvent("location", ({ to }) => to.pathname);
+
+// Or run a side effect only
+useEvent("auth", ({ prev, next }) => {
+  if (!prev.isAuthenticated && next.isAuthenticated) {
+    trackSignIn(next.profile);
+  }
+});
+```
+
+## `useExposedProps`
+
+Convenience wrapper around React Router's hooks. Returns the props Dev Portal passes to `custom-page`
+navigation entries, so you get the same shape whether you're writing a page component or a slot.
+
+```typescript
+import { useExposedProps } from "zudoku/hooks";
+
+const { location, navigate, params, searchParams, setSearchParams } = useExposedProps();
+```
+
+## `useCache`
+
+Invalidates Zudoku's internal React Query caches. Today this supports `API_IDENTITIES`, which is
+useful when you change something that affects the identities available to the API playground (for
+example after a user creates a new API key).
+
+```typescript
+import { useCache } from "zudoku/hooks";
+
+const { invalidateCache } = useCache();
+
+await invalidateCache("API_IDENTITIES");
+```
+
+## Re-exported hooks
+
+For convenience, Dev Portal re-exports two hooks from its underlying libraries:
+
+- `useTheme` from [`next-themes`](https://github.com/pacocoursey/next-themes#usetheme) — read or
+  change the active color scheme (`light`, `dark`, or `system`).
+- `useMDXComponents` from [`@mdx-js/react`](https://mdxjs.com/packages/react/) — access the MDX
+  component mapping when rendering MDX content inside a custom component.
+
+```typescript
+import { useMDXComponents, useTheme } from "zudoku/hooks";
+```

package/docs/dev-portal/zudoku/markdown/frontmatter.md

@@ -95,6 +95,25 @@ toc: false
 ---
 ```
 
+### `fullWidth`
+
+Removes the table of contents sidebar and lets the page content span the full available width. When
+enabled, the table of contents is still accessible via an "On this page" toggle in the page header
+(unless `toc: false` is also set, in which case it is hidden entirely).
+
+```md
+---
+fullWidth: true
+---
+```
+
+| `fullWidth` | `toc`   | Result                                                          |
+| ----------- | ------- | --------------------------------------------------------------- |
+| `false`     | `true`  | TOC shown in the sidebar (default).                             |
+| `false`     | `false` | TOC hidden; content keeps its standard width.                   |
+| `true`      | `true`  | Content spans full width; TOC is available via a toggle button. |
+| `true`      | `false` | Content spans full width; TOC is not available at all.          |
+
 ### `disable_pager`
 
 Controls whether the previous/next page navigation is displayed at the bottom of the page. Set to

package/docs/policies/upstream-gcp-service-auth-inbound/schema.json

@@ -75,6 +75,12 @@
               "enum": [1, 2],
               "x-show-example": false,
               "description": "The version of the policy."
+            },
+            "enableSuspiciousHeaderWarning": {
+              "type": "boolean",
+              "default": true,
+              "x-show-example": false,
+              "description": "When `true` (the default), emits a warning if the inbound request carries headers like `X-Serverless-Authorization` or `X-Goog-IAP-JWT-Assertion`. Forwarding those to a downstream Cloud Run typically causes a `the access token could not be verified` 401 because Cloud Run prefers `X-Serverless-Authorization` over `Authorization` for IAM checks. Set this to `false` only if you have intentionally chosen to forward those headers (e.g. the upstream service is also IAP-fronted and expects them) — the warning is otherwise a useful diagnostic signal."
             }
           }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.69.6",
+  "version": "6.69.8",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.69.6",
-    "@zuplo/core": "6.69.6",
-    "@zuplo/runtime": "6.69.6",
+    "@zuplo/cli": "6.69.8",
+    "@zuplo/core": "6.69.8",
+    "@zuplo/runtime": "6.69.8",
     "@zuplo/test": "1.4.0"
   }
 }