@stigmer/react 0.0.89 → 0.0.91

package/src/platform-client/useCreatePlatformClient.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { PlatformClientInput } from "@stigmer/sdk";
+import type { PlatformClientCreateResponse } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useCreatePlatformClient}. */
+export interface UseCreatePlatformClientReturn {
+  /**
+   * Submit a {@link PlatformClientInput} to create a new platform client.
+   * Resolves with a {@link PlatformClientCreateResponse} containing the
+   * resource and the **one-time raw client secret**.
+   */
+  readonly create: (
+    input: PlatformClientInput,
+  ) => Promise<PlatformClientCreateResponse>;
+  /** `true` while the create request is in flight. */
+  readonly isCreating: boolean;
+  /** Error from the last failed create, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that wraps `platformclient.create()` with loading
+ * and error state.
+ *
+ * Creates a platform client resource within an organization. The
+ * response includes a **one-time raw client secret** that must be
+ * shown to the user immediately — the server never returns it again.
+ *
+ * @example
+ * ```tsx
+ * const { create, isCreating, error } = useCreatePlatformClient();
+ *
+ * const response = await create({
+ *   name: "my-saas-backend",
+ *   org: "acme",
+ *   autoProvisionAccounts: true,
+ *   autoGrantOnOrg: true,
+ * });
+ *
+ * // response.clientSecret is the one-time raw secret
+ * // response.platformClient is the created resource
+ * ```
+ */
+export function useCreatePlatformClient(): UseCreatePlatformClientReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (
+      input: PlatformClientInput,
+    ): Promise<PlatformClientCreateResponse> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.platformclient.create(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/platform-client/useDeletePlatformClient.ts

@@ -0,0 +1,64 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { DeleteResourceInput } from "@stigmer/sdk";
+import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useDeletePlatformClient}. */
+export interface UseDeletePlatformClientReturn {
+  /** Delete a platform client. Resolves with the deleted resource for confirmation display. */
+  readonly deletePlatformClient: (
+    input: DeleteResourceInput,
+  ) => Promise<PlatformClient>;
+  /** `true` while the delete request is in flight. */
+  readonly isDeleting: boolean;
+  /** Error from the last failed delete, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that wraps `platformclient.delete()` with loading
+ * and error state.
+ *
+ * Deletes a platform client by its resource ID. Returns the deleted
+ * {@link PlatformClient} on success so callers can confirm which
+ * resource was removed.
+ *
+ * @example
+ * ```tsx
+ * const { deletePlatformClient, isDeleting, error } = useDeletePlatformClient();
+ *
+ * await deletePlatformClient({ resourceId: "pc-abc123" });
+ * refetch(); // refresh the list after deletion
+ * ```
+ */
+export function useDeletePlatformClient(): UseDeletePlatformClientReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const deletePlatformClient = useCallback(
+    async (input: DeleteResourceInput): Promise<PlatformClient> => {
+      setIsDeleting(true);
+      setError(null);
+
+      try {
+        return await stigmer.platformclient.delete(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsDeleting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { deletePlatformClient, isDeleting, error, clearError };
+}

package/src/platform-client/usePlatformClient.ts

@@ -0,0 +1,86 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link usePlatformClient}. */
+export interface UsePlatformClientReturn {
+  /** The fetched PlatformClient, or `null` while loading or on error. */
+  readonly platformClient: PlatformClient | null;
+  /** `true` while the initial fetch or a refetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a single PlatformClient by ID.
+ *
+ * Pass `null` to skip fetching (stable no-op). When the `id` changes,
+ * the previous in-flight request is discarded and a fresh fetch begins.
+ *
+ * Returns the full proto {@link PlatformClient} resource so consumers
+ * have access to metadata, spec (client ID, expiry, JIT config), and
+ * status without additional calls.
+ *
+ * @example
+ * ```tsx
+ * function PlatformClientDetail({ pcId }: { pcId: string }) {
+ *   const { platformClient, isLoading, error } = usePlatformClient(pcId);
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *   if (!platformClient) return <NotFound />;
+ *
+ *   return <h1>{platformClient.metadata?.name}</h1>;
+ * }
+ * ```
+ */
+export function usePlatformClient(
+  id: string | null,
+): UsePlatformClientReturn {
+  const stigmer = useStigmer();
+  const [platformClient, setPlatformClient] =
+    useState<PlatformClient | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!id) {
+      setPlatformClient(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    stigmer.platformclient.get(id).then(
+      (result) => {
+        if (cancelled.current) return;
+        setPlatformClient(result);
+        setIsLoading(false);
+      },
+      (err) => {
+        if (cancelled.current) return;
+        setError(toError(err));
+        setIsLoading(false);
+      },
+    );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [id, stigmer, fetchKey]);
+
+  return { platformClient, isLoading, error, refetch };
+}

package/src/platform-client/usePlatformClientList.ts

@@ -0,0 +1,96 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import { ListPlatformClientsByOrgInputSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link usePlatformClientList}. */
+export interface UsePlatformClientListReturn {
+  /** All platform clients for the organization. Empty while loading or on error. */
+  readonly platformClients: readonly PlatformClient[];
+  /** `true` while the initial fetch or a refetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches all platform clients for an organization.
+ *
+ * Platform clients are admin-level resources with small cardinality
+ * (typically 1–5 per org), so results are returned as a flat list
+ * without pagination.
+ *
+ * Pass `null` to skip fetching (stable no-op). Call `refetch()` to
+ * re-query after mutations (create / update / delete / rotateSecret).
+ *
+ * @example
+ * ```tsx
+ * function PlatformClientSettings({ org }: { org: string }) {
+ *   const { platformClients, isLoading, error } = usePlatformClientList(org);
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *
+ *   return (
+ *     <ul>
+ *       {platformClients.map((pc) => (
+ *         <li key={pc.metadata?.id}>{pc.metadata?.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function usePlatformClientList(
+  org: string | null,
+): UsePlatformClientListReturn {
+  const stigmer = useStigmer();
+  const [platformClients, setPlatformClients] = useState<PlatformClient[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!org) {
+      setPlatformClients([]);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    stigmer.platformclient
+      .listByOrg(
+        create(ListPlatformClientsByOrgInputSchema, { org }),
+      )
+      .then(
+        (result) => {
+          if (cancelled.current) return;
+          setPlatformClients([...result.entries]);
+          setIsLoading(false);
+        },
+        (err) => {
+          if (cancelled.current) return;
+          setError(toError(err));
+          setIsLoading(false);
+        },
+      );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [org, stigmer, fetchKey]);
+
+  return { platformClients, isLoading, error, refetch };
+}

package/src/platform-client/useRotatePlatformClientSecret.ts

@@ -0,0 +1,68 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { PlatformClientCreateResponse } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useRotatePlatformClientSecret}. */
+export interface UseRotatePlatformClientSecretReturn {
+  /**
+   * Rotate the client secret for a platform client by its resource ID.
+   * Resolves with a {@link PlatformClientCreateResponse} containing the
+   * updated resource and the **one-time new raw client secret**.
+   */
+  readonly rotateSecret: (
+    id: string,
+  ) => Promise<PlatformClientCreateResponse>;
+  /** `true` while the rotation request is in flight. */
+  readonly isRotating: boolean;
+  /** Error from the last failed rotation, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that wraps `platformclient.rotateSecret()` with
+ * loading and error state.
+ *
+ * Generates a new client secret, invalidating the previous one.
+ * The response includes a **one-time raw client secret** — it must
+ * be shown to the user immediately as the server never returns it
+ * again.
+ *
+ * @example
+ * ```tsx
+ * const { rotateSecret, isRotating, error } = useRotatePlatformClientSecret();
+ *
+ * const response = await rotateSecret("pc-abc123");
+ * // response.clientSecret is the new one-time raw secret
+ * ```
+ */
+export function useRotatePlatformClientSecret(): UseRotatePlatformClientSecretReturn {
+  const stigmer = useStigmer();
+  const [isRotating, setIsRotating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const rotateSecret = useCallback(
+    async (id: string): Promise<PlatformClientCreateResponse> => {
+      setIsRotating(true);
+      setError(null);
+
+      try {
+        return await stigmer.platformclient.rotateSecret(id);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsRotating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { rotateSecret, isRotating, error, clearError };
+}

package/src/platform-client/useUpdatePlatformClient.ts

@@ -0,0 +1,70 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { PlatformClientInput } from "@stigmer/sdk";
+import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useUpdatePlatformClient}. */
+export interface UseUpdatePlatformClientReturn {
+  /** Submit a {@link PlatformClientInput} to update an existing platform client. Resolves with the updated resource. */
+  readonly update: (input: PlatformClientInput) => Promise<PlatformClient>;
+  /** `true` while the update request is in flight. */
+  readonly isUpdating: boolean;
+  /** Error from the last failed update, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that wraps `platformclient.update()` with loading
+ * and error state.
+ *
+ * Updates an existing platform client. The input must include the
+ * `slug` field to identify the target resource, along with the
+ * updated spec fields. Credential fields (`clientId`,
+ * `clientSecretHash`, `secretFingerprint`) are computed and
+ * preserved by the backend — do not set them in the input.
+ *
+ * @example
+ * ```tsx
+ * const { update, isUpdating, error } = useUpdatePlatformClient();
+ *
+ * await update({
+ *   name: "my-saas-backend",
+ *   slug: "my-saas-backend",
+ *   org: "acme",
+ *   autoProvisionAccounts: true,
+ *   autoGrantOnOrg: true,
+ * });
+ * refetch(); // refresh detail view
+ * ```
+ */
+export function useUpdatePlatformClient(): UseUpdatePlatformClientReturn {
+  const stigmer = useStigmer();
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const update = useCallback(
+    async (input: PlatformClientInput): Promise<PlatformClient> => {
+      setIsUpdating(true);
+      setError(null);
+
+      try {
+        return await stigmer.platformclient.update(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsUpdating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { update, isUpdating, error, clearError };
+}

package/src/test/index.ts

@@ -0,0 +1,6 @@
+// @stigmer/react/test — test utilities for Stigmer SDK components.
+//
+// Provides domain-specific data builders for unit tests, Storybook,
+// Playwright, and Scenar preview scenarios.
+
+export { samples } from "./samples";

package/src/{demo → test}/samples.ts

@@ -171,7 +171,7 @@ export interface SearchResultOverrides {
  *
  * @example
  * ```ts
- * import { samples, fixtures, buildScenario } from "@stigmer/react/demo";
+ * import { samples } from "@stigmer/react/test";
  *
  * const scenario = buildScenario(
  *   fixtures.session.get(() => samples.session({ subject: "My topic" })),