@stigmer/react 3.2.2 → 3.3.0

package/src/cursor-accounts/useDeleteCursorAccount.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { CursorAccount } from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/cursor_account_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Input for {@link useDeleteCursorAccount}. */
+export interface DeleteCursorAccountInput {
+  readonly accountId: string;
+  /**
+   * Deletion is refused (FAILED_PRECONDITION) while live sessions are
+   * pinned to the account's keys. `force: true` overrides — their Cursor
+   * agent handles will be orphaned at disposal. Prefer disabling the
+   * account, which is always safe.
+   */
+  readonly force?: boolean;
+}
+
+/** Return value of {@link useDeleteCursorAccount}. */
+export interface UseDeleteCursorAccountReturn {
+  /** Delete the account (plus its snapshots and session pins). */
+  readonly remove: (input: DeleteCursorAccountInput) => Promise<CursorAccount>;
+  /** `true` while a delete is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook for deleting a managed Cursor account. The live-pin
+ * guard's FAILED_PRECONDITION message carries the pinned session count —
+ * surface it verbatim so the operator can choose disable-instead.
+ */
+export function useDeleteCursorAccount(): UseDeleteCursorAccountReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const remove = useCallback(
+    async (input: DeleteCursorAccountInput): Promise<CursorAccount> => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        return await stigmer.cursorAccounts.deleteAccount(input);
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer.cursorAccounts],
+  );
+
+  const clearError = useCallback(() => setError(null), []);
+
+  return { remove, isSubmitting, error, clearError };
+}

package/src/cursor-accounts/useSyncCursorAccount.ts

@@ -0,0 +1,54 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { CursorAccountView } from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useSyncCursorAccount}. */
+export interface UseSyncCursorAccountReturn {
+  /**
+   * Run an on-demand roster + spend sync and return the refreshed view.
+   * The Cursor Admin API is rate-limited (20 req/min, poll-hourly
+   * guidance) — `isSyncing` should disable the trigger while in flight,
+   * and callers should not poll this.
+   */
+  readonly sync: (accountId: string) => Promise<CursorAccountView>;
+  /** `true` while a sync is in flight. */
+  readonly isSyncing: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook for the console's "Sync now" — the same server-side sync
+ * the hourly schedule runs, on demand.
+ */
+export function useSyncCursorAccount(): UseSyncCursorAccountReturn {
+  const stigmer = useStigmer();
+  const [isSyncing, setIsSyncing] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const sync = useCallback(
+    async (accountId: string): Promise<CursorAccountView> => {
+      setIsSyncing(true);
+      setError(null);
+      try {
+        return await stigmer.cursorAccounts.syncAccount(accountId);
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        throw err;
+      } finally {
+        setIsSyncing(false);
+      }
+    },
+    [stigmer.cursorAccounts],
+  );
+
+  const clearError = useCallback(() => setError(null), []);
+
+  return { sync, isSyncing, error, clearError };
+}

package/src/cursor-accounts/useUpsertCursorAccount.ts

@@ -0,0 +1,57 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { CursorAccount } from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/cursor_account_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useUpsertCursorAccount}. */
+export interface UseUpsertCursorAccountReturn {
+  /**
+   * Create (empty `accountId`) or update a Cursor account. The admin key
+   * is plaintext to set/rotate or the `***REDACTED***` marker to keep the
+   * stored value; the server validates new keys live against Cursor's
+   * `/teams/members` before persisting. Returns the redacted account.
+   */
+  readonly upsert: (account: CursorAccount) => Promise<CursorAccount>;
+  /** `true` while a save is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook for creating or updating a managed Cursor account.
+ *
+ * The parent should refetch its list/detail view after a successful
+ * save — org assignments affect key selection within the proxy's cache
+ * TTL (~5 minutes).
+ */
+export function useUpsertCursorAccount(): UseUpsertCursorAccountReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const upsert = useCallback(
+    async (account: CursorAccount): Promise<CursorAccount> => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        return await stigmer.cursorAccounts.upsertAccount({ account });
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer.cursorAccounts],
+  );
+
+  const clearError = useCallback(() => setError(null), []);
+
+  return { upsert, isSubmitting, error, clearError };
+}