@notis_ai/cli 0.2.13 → 0.2.15

package/template/packages/sdk/src/hooks/useDatabaseSubscription.ts

@@ -0,0 +1,76 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useDocuments, type UseDocumentsOptions, type UseDocumentsResult } from './useDocuments';
+import type { DocumentRecord } from '../runtime';
+
+export interface UseDatabaseSubscriptionOptions extends UseDocumentsOptions {
+  /** Set to false to keep the query but skip the change feed. */
+  subscribe?: boolean;
+}
+
+export interface UseDatabaseSubscriptionResult extends UseDocumentsResult {
+  /** Alias of `documents`, for views that think in rows. */
+  rows: DocumentRecord[];
+  /** True while a live change feed is attached to this database. */
+  live: boolean;
+}
+
+/**
+ * Query a Notis database and keep it fresh without polling.
+ *
+ * ```tsx
+ * const { rows, live, refetch } = useDatabaseSubscription('workspaces');
+ * ```
+ *
+ * A change on the database wakes the hook, which then refetches through the
+ * usual `LOCAL_NOTIS_DATABASE_QUERY` path — the change feed is a signal only
+ * and never carries row data. Hosts without a change feed (the dev harness,
+ * the screenshot stub, the vite preview) still return rows; `live` is false
+ * there and the app should keep offering its manual refresh.
+ */
+export function useDatabaseSubscription(
+  databaseSlug: string,
+  options: UseDatabaseSubscriptionOptions = {},
+): UseDatabaseSubscriptionResult {
+  const runtime = useNotisRuntime();
+  const { subscribe = true, ...documentOptions } = options;
+  const { documents, loading, error, refetch } = useDocuments(databaseSlug, documentOptions);
+  const [live, setLive] = useState(false);
+
+  const refetchRef = useRef(refetch);
+  useEffect(() => {
+    refetchRef.current = refetch;
+  }, [refetch]);
+
+  const enabled = options.enabled !== false && subscribe;
+
+  useEffect(() => {
+    if (!runtime?.subscribeDatabase || !enabled || !databaseSlug) {
+      setLive(false);
+      return;
+    }
+
+    let cancelled = false;
+    const unsubscribe = runtime.subscribeDatabase(
+      databaseSlug,
+      () => {
+        refetchRef.current();
+      },
+      {
+        onStatusChange: (isLive) => {
+          if (!cancelled) setLive(isLive);
+        },
+      },
+    );
+
+    return () => {
+      cancelled = true;
+      setLive(false);
+      unsubscribe?.();
+    };
+  }, [runtime, databaseSlug, enabled]);
+
+  return { documents, rows: documents, loading, error, refetch, live };
+}

package/template/packages/sdk/src/hooks/useHandover.ts

@@ -0,0 +1,78 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { HandoverPayload, HandoverResult } from '../runtime';
+
+export interface UseHandoverResult {
+  /** Hand the work over. Rejects when the host has no manager chat. */
+  handover: (payload: HandoverPayload) => Promise<HandoverResult>;
+  /** True while the manager chat is being prepared. */
+  pending: boolean;
+  error: Error | null;
+  /**
+   * False when the host cannot hand work over (dev harness, vite preview).
+   * Render the app's own fallback — a copyable prompt, say — when it is false.
+   */
+  available: boolean;
+}
+
+/**
+ * Hand a piece of work from app code to the Notis manager chat.
+ *
+ * An app displays work; the manager runs it. `handover` puts the message in
+ * the chat surface that already owns streaming progress, billing, cancellation
+ * and the transcript, and the app watches its own databases for the result.
+ *
+ * ```tsx
+ * const { handover, pending, available } = useHandover();
+ *
+ * return available ? (
+ *   <Button
+ *     disabled={pending}
+ *     onClick={() => { void handover({ prompt: 'Create a workspace on notis to ...' }); }}
+ *   >
+ *     Send to Notis
+ *   </Button>
+ * ) : (
+ *   <CopyablePrompt prompt="Create a workspace on notis to ..." />
+ * );
+ * ```
+ *
+ * Omit `prompt` to open a context-only composer, for example when a visible
+ * feedback button should let the user write in their own words.
+ *
+ * Pass `skill` to bind the work to a skill declared in `notis.config.ts`; the
+ * host rejects a key the app does not declare. `autoSend` is accepted for
+ * forward compatibility; today's hosts always return `drafted` and let the
+ * user press send.
+ */
+export function useHandover(): UseHandoverResult {
+  const runtime = useNotisRuntime();
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const handover = useCallback(
+    async (payload: HandoverPayload): Promise<HandoverResult> => {
+      if (!runtime?.handover) {
+        throw new Error('This Notis host cannot hand work to the manager chat.');
+      }
+
+      setPending(true);
+      setError(null);
+
+      try {
+        return await runtime.handover(payload);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    [runtime],
+  );
+
+  return { handover, pending, error, available: Boolean(runtime?.handover) };
+}