@notis_ai/cli 0.2.5 → 0.2.7

package/dist/scaffolds/notis-journal/packages/sdk/src/hooks/useTools.ts

@@ -0,0 +1,56 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { ToolDescriptor } from '../runtime';
+
+interface UseToolsResult {
+  tools: ToolDescriptor[];
+  loading: boolean;
+  error: Error | null;
+}
+
+/**
+ * List all tools available to this app.
+ *
+ * ```tsx
+ * const { tools, loading } = useTools();
+ * ```
+ */
+export function useTools(): UseToolsResult {
+  const runtime = useNotisRuntime();
+  const [tools, setTools] = useState<ToolDescriptor[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!runtime) {
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+
+    runtime
+      .listTools()
+      .then((result) => {
+        if (!cancelled) {
+          setTools(result);
+          setLoading(false);
+        }
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+          setLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime]);
+
+  return { tools, loading, error };
+}

package/dist/scaffolds/notis-journal/packages/sdk/src/hooks/useTopBarSearch.ts

@@ -0,0 +1,73 @@
+'use client';
+
+import { useCallback, useEffect } from 'react';
+import { useNotisRuntime } from '../provider';
+
+interface TopBarSearchOptions {
+  /** Current value shown in the top bar search input. */
+  value: string;
+  /** Called when the user types in the top bar. */
+  onChange: (value: string) => void;
+  /** Placeholder text for the input. Defaults to 'Search…'. */
+  placeholder?: string;
+  /** Called when the user presses Enter. May return a Promise. */
+  onSubmit?: () => void | Promise<void>;
+}
+
+interface TopBarSearchActions {
+  /** Toggle the loader that replaces the search icon in the top bar. */
+  setLoading: (loading: boolean) => void;
+}
+
+/**
+ * Registers this view's search binding with the portal's top bar search input.
+ * While the component is mounted, typing in the top bar calls `onChange`,
+ * pressing Enter calls `onSubmit`, and the `value` prop drives the input.
+ *
+ * Call `setLoading(true)` to show the standard spinner in the top bar while a
+ * query is running; `setLoading(false)` restores the search icon.
+ *
+ * Without a portal runtime, this hook is a safe no-op.
+ *
+ * ```tsx
+ * const [q, setQ] = useState('');
+ * const { setLoading } = useTopBarSearch({
+ *   value: q,
+ *   onChange: setQ,
+ *   placeholder: 'Search notes…',
+ *   onSubmit: async () => {
+ *     setLoading(true);
+ *     try { await runSearch(q); } finally { setLoading(false); }
+ *   },
+ * });
+ * ```
+ *
+ * Stabilize `onChange` and `onSubmit` with `useCallback` to avoid re-registering
+ * on every render.
+ */
+export function useTopBarSearch(opts: TopBarSearchOptions): TopBarSearchActions {
+  const runtime = useNotisRuntime();
+  const { value, onChange, placeholder, onSubmit } = opts;
+
+  useEffect(() => {
+    const register = runtime?.registerTopBarSearch;
+    if (!register) return;
+    register({ onChange, placeholder, onSubmit });
+    return () => {
+      register(null);
+    };
+  }, [runtime, onChange, placeholder, onSubmit]);
+
+  useEffect(() => {
+    runtime?.setTopBarSearchValue?.(value);
+  }, [runtime, value]);
+
+  const setLoading = useCallback(
+    (loading: boolean) => {
+      runtime?.setTopBarSearchLoading?.(loading);
+    },
+    [runtime],
+  );
+
+  return { setLoading };
+}

package/dist/scaffolds/notis-journal/packages/sdk/src/hooks/useUpsertDocument.ts

@@ -0,0 +1,95 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord } from '../runtime';
+
+export interface UpsertDocumentArgs {
+  documentId?: string;
+  title?: string;
+  /** Property values keyed by property name (already-plain values). */
+  properties?: Record<string, unknown>;
+  /** Markdown content; converted server-side to BlockNote. Exclusive with contentBlocknote. */
+  contentMarkdown?: string | null;
+  /** BlockNote block JSON. Exclusive with contentMarkdown. */
+  contentBlocknote?: Array<Record<string, unknown>> | null;
+  /** 'archive' soft-deletes the document (sets archived_at); 'restore' undoes it. */
+  operation?: 'create' | 'update' | 'archive' | 'restore';
+}
+
+interface UpsertToolResult {
+  status?: string;
+  document?: unknown;
+  message?: string;
+  error?: string;
+}
+
+export interface UseUpsertDocumentResult {
+  upsert: (args: UpsertDocumentArgs) => Promise<DocumentRecord>;
+  loading: boolean;
+  error: Error | null;
+}
+
+function upsertToolName(databaseSlug: string): string {
+  return `LOCAL_NOTIS_DATABASE_UPSERT_${databaseSlug.replace(/-/g, '_').toUpperCase()}`;
+}
+
+function buildToolArgs(args: UpsertDocumentArgs): Record<string, unknown> {
+  const payload: Record<string, unknown> = {};
+  if (args.documentId) payload.document_id = args.documentId;
+  if (typeof args.title === 'string') payload.title = args.title;
+  if (args.properties) Object.assign(payload, args.properties);
+  if ('contentMarkdown' in args) payload.content_markdown = args.contentMarkdown ?? '';
+  if ('contentBlocknote' in args) payload.content_blocknote = args.contentBlocknote ?? null;
+  if (args.operation) payload.operation = args.operation;
+  return payload;
+}
+
+/**
+ * Create/update/archive documents in a Notis database.
+ *
+ * ```tsx
+ * const { upsert } = useUpsertDocument('journal_entries');
+ * await upsert({ documentId, properties: { Mood: 'Great' }, contentMarkdown: reflection });
+ * ```
+ */
+export function useUpsertDocument(databaseSlug: string): UseUpsertDocumentResult {
+  const runtime = useNotisRuntime();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const upsert = useCallback(
+    async (args: UpsertDocumentArgs): Promise<DocumentRecord> => {
+      if (!runtime) {
+        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
+      }
+      if ('contentMarkdown' in args && 'contentBlocknote' in args) {
+        throw new Error('Provide contentMarkdown or contentBlocknote, not both.');
+      }
+
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await runtime.callTool<UpsertToolResult>(
+          upsertToolName(databaseSlug),
+          buildToolArgs(args),
+        );
+        if (!result.document) {
+          throw new Error(result.error ?? result.message ?? 'Failed to save document');
+        }
+        return normalizeDocumentRecord(result.document);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [runtime, databaseSlug],
+  );
+
+  return { upsert, loading, error };
+}

package/dist/scaffolds/notis-journal/packages/sdk/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * @notis/sdk - The Notis App SDK
+ *
+ * Public API for building Notis apps. Import hooks and the provider from
+ * this entrypoint. For configuration, use `@notis/sdk/config`. For the
+ * Vite config builder, use `@notis/sdk/vite`.
+ */
+
+// Provider
+export { NotisProvider, useNotisRuntime } from './provider';
+
+// Hooks
+export { useNotis } from './hooks/useNotis';
+export { useDocuments } from './hooks/useDocuments';
+export type { UseDocumentsOptions, UseDocumentsResult } from './hooks/useDocuments';
+export { useDocument } from './hooks/useDocument';
+export type { UseDocumentOptions, UseDocumentResult } from './hooks/useDocument';
+export { useUpsertDocument } from './hooks/useUpsertDocument';
+export type { UpsertDocumentArgs, UseUpsertDocumentResult } from './hooks/useUpsertDocument';
+export { useDatabaseSchema } from './hooks/useDatabaseSchema';
+export type { UseDatabaseSchemaResult } from './hooks/useDatabaseSchema';
+export { useTool } from './hooks/useTool';
+export type { ToolCallState, UseToolResult } from './hooks/useTool';
+export { useTools } from './hooks/useTools';
+export { useNotisNavigation } from './hooks/useNotisNavigation';
+export { useTopBarSearch } from './hooks/useTopBarSearch';
+export { useBackend } from './hooks/useBackend';
+export { useMultiSelect } from './hooks/useMultiSelect';
+
+// Documents & markdown
+export { Markdown } from './components/Markdown';
+export type { MarkdownProps } from './components/Markdown';
+export { DocumentEditor } from './components/DocumentEditor';
+export {
+  asRecord,
+  blockNoteToPlainText,
+  extractRichText,
+  getDocumentPreview,
+  getRelationIds,
+  isPresentString,
+  markdownToPlainText,
+  normalizeDatabaseProperty,
+  normalizeDocumentRecord,
+  normalizePropertyValue,
+  optionalString,
+} from './documents';
+
+// Multi-select components
+export { MultiSelectActionBar } from './components/MultiSelectActionBar';
+export { MultiSelectCheckbox } from './components/MultiSelectCheckbox';
+export { MultiSelectDragOverlay } from './components/MultiSelectDragOverlay';
+export type {
+  DragRect,
+  MultiSelectController,
+  UseMultiSelectOptions,
+} from './hooks/useMultiSelect';
+export type {
+  MultiSelectAction,
+  MultiSelectActionBarProps,
+} from './components/MultiSelectActionBar';
+export type { MultiSelectCheckboxProps } from './components/MultiSelectCheckbox';
+export type { MultiSelectDragOverlayProps } from './components/MultiSelectDragOverlay';
+
+// Types (re-exported for convenience)
+export type {
+  AppDescriptor,
+  CollectionItem,
+  CollectionItemDetail,
+  DatabaseDescriptor,
+  DatabaseProperty,
+  DatabasePropertyOption,
+  DatabasePropertyType,
+  DocumentContentType,
+  DocumentRecord,
+  NotisDocumentEditorProps,
+  NotisRuntime,
+  NotisRuntimeContext,
+  NotisRuntimeUI,
+  QueryFilter,
+  RouteDescriptor,
+  ToolDescriptor,
+  ToolInputSchema,
+} from './runtime';

package/dist/scaffolds/notis-journal/packages/sdk/src/provider.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import React, { createContext, useContext, type Context, type ReactNode } from 'react';
+import type { NotisRuntime } from './runtime';
+
+const NOTIS_CONTEXT_SYMBOL = Symbol.for('notis.sdk.runtime_context');
+
+type NotisContextGlobal = typeof globalThis & {
+  [NOTIS_CONTEXT_SYMBOL]?: Context<NotisRuntime | null>;
+};
+
+function getNotisContext(): Context<NotisRuntime | null> {
+  const scope = globalThis as NotisContextGlobal;
+  if (!scope[NOTIS_CONTEXT_SYMBOL]) {
+    scope[NOTIS_CONTEXT_SYMBOL] = createContext<NotisRuntime | null>(null);
+  }
+  return scope[NOTIS_CONTEXT_SYMBOL]!;
+}
+
+const NotisContext = getNotisContext();
+
+/**
+ * Provides the Notis runtime context to all child components. The portal owns
+ * the runtime and injects it into the rendered app tree.
+ */
+export function NotisProvider({ children, runtime }: { children: ReactNode; runtime: NotisRuntime | null }) {
+  if (runtime === undefined) {
+    throw new Error('NotisProvider requires an explicit runtime prop.');
+  }
+  return (
+    <NotisContext.Provider value={runtime}>
+      {children}
+    </NotisContext.Provider>
+  );
+}
+
+/**
+ * Returns the raw NotisRuntime or null if not yet available.
+ * Prefer the typed hooks (useTool, useNotis, etc.) over this.
+ */
+export function useNotisRuntime(): NotisRuntime | null {
+  return useContext(NotisContext);
+}

package/dist/scaffolds/notis-journal/packages/sdk/src/runtime.ts

@@ -0,0 +1,220 @@
+/**
+ * NotisRuntime is the bridge between app code running in the browser and the
+ * Notis platform. The portal owns the runtime and injects it through
+ * `NotisProvider` when the app is rendered.
+ *
+ * App code should never reach for globals. Use the hooks from `@notis/sdk`
+ * (useTool, useNotis, etc.) which read from the NotisProvider context.
+ */
+
+import type { ComponentType } from 'react';
+
+// ---------------------------------------------------------------------------
+// Database types
+// ---------------------------------------------------------------------------
+
+export type DatabasePropertyType =
+  | 'title'
+  | 'rich_text'
+  | 'text'
+  | 'number'
+  | 'checkbox'
+  | 'date'
+  | 'select'
+  | 'multi_select'
+  | 'status'
+  | 'relation'
+  | 'formula'
+  | 'files';
+
+export interface DatabasePropertyOption {
+  id?: string | null;
+  name: string;
+  color?: string | null;
+  order?: number;
+}
+
+export interface DatabaseProperty {
+  id?: string | null;
+  name: string;
+  type: DatabasePropertyType;
+  description?: string | null;
+  options?: DatabasePropertyOption[];
+}
+
+export interface DatabaseDescriptor {
+  slug: string;
+  title: string;
+  description?: string | null;
+  icon?: string | null;
+  properties: DatabaseProperty[];
+}
+
+/**
+ * A document's content is typed. `markdown` documents carry rich text as
+ * BlockNote JSON (canonical) with a derived markdown projection; `file`
+ * documents carry an uploaded file whose format is in `fileType`
+ * (pdf, xlsx, pptx, ...). Future content types (canvas, ...) extend this
+ * union without changing the component contracts.
+ */
+export type DocumentContentType = 'markdown' | 'file';
+
+export interface DocumentRecord {
+  id: string;
+  title: string;
+  properties: Record<string, unknown>;
+  url?: string | null;
+  icon?: string | null;
+  cover?: string | null;
+  databaseSlug?: string;
+  contentType?: DocumentContentType | null;
+  fileType?: string | null;
+  contentBlocknote?: Array<Record<string, unknown>> | null;
+  contentMarkdown?: string | null;
+  plainText?: string | null;
+  createdAt?: string | null;
+  lastEditedTime?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Tool types
+// ---------------------------------------------------------------------------
+
+export type ToolInputSchema = Record<string, unknown>;
+
+export interface ToolDescriptor {
+  name: string;
+  description?: string;
+  inputSchema?: ToolInputSchema;
+}
+
+// ---------------------------------------------------------------------------
+// Route types
+// ---------------------------------------------------------------------------
+
+export interface RouteDescriptor {
+  slug: string;
+  path: string;
+  name: string;
+  icon?: string | null;
+  parentSlug?: string | null;
+  default?: boolean;
+  collection?: {
+    database: string;
+    titleProperty: string;
+    parentProperty?: string | null;
+    sidebar?: {
+      mode: 'flat-list' | 'tree';
+      allowCreate: boolean;
+    } | null;
+  } | null;
+}
+
+export interface CollectionItem {
+  id: string;
+  title: string;
+  icon?: string | null;
+}
+
+export interface CollectionItemDetail extends CollectionItem {
+  properties: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// App descriptor
+// ---------------------------------------------------------------------------
+
+export interface AppDescriptor {
+  id: string;
+  name: string;
+  icon?: string | null;
+  description?: string | null;
+}
+
+export interface QueryFilter {
+  filters?: Array<{
+    property: string;
+    operator: string;
+    type?: string;
+    value: unknown;
+  }>;
+  sorts?: Array<{
+    property: string;
+    direction: 'asc' | 'desc';
+  }>;
+  page_size?: number;
+}
+
+export interface NotisRuntimeContext {
+  collectionItem?: CollectionItemDetail | null;
+  /**
+   * Set when the app is being rendered by the screenshot harness (`notis apps
+   * screenshot`) for the named listing scenario. Lets apps and SDK components
+   * hide dev-only chrome from listing images.
+   */
+  screenshotScenario?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Host-provided UI
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for the host-provided document editor. The host implementation
+ * dispatches on the document's content type (markdown -> rich text editor,
+ * file -> matching viewer/editor), so this contract stays stable as new
+ * content types ship.
+ */
+export interface NotisDocumentEditorProps {
+  documentId: string;
+  /** 'full' renders icon/title/cover above the content; 'body' renders content only. */
+  variant?: 'full' | 'body';
+  readOnly?: boolean;
+  className?: string;
+  onDirtyChange?: (dirty: boolean) => void;
+  onSavingChange?: (saving: boolean) => void;
+}
+
+/**
+ * Components the host (portal) injects through the runtime. Apps consume them
+ * via the SDK wrappers (e.g. `DocumentEditor`), which fall back gracefully
+ * when a host component is unavailable (standalone dev harness, snapshots).
+ */
+export interface NotisRuntimeUI {
+  DocumentEditor?: ComponentType<NotisDocumentEditorProps>;
+}
+
+// ---------------------------------------------------------------------------
+// NotisRuntime
+// ---------------------------------------------------------------------------
+
+export interface NotisRuntime {
+  app: AppDescriptor;
+  route: RouteDescriptor;
+  databases: DatabaseDescriptor[];
+  context: NotisRuntimeContext;
+  ui?: NotisRuntimeUI;
+
+  navigate?: (payload: { kind: string; [key: string]: unknown }) => void;
+
+  registerTopBarSearch?: (
+    config:
+      | {
+          onChange: (value: string) => void;
+          placeholder?: string;
+          onSubmit?: () => void | Promise<void>;
+        }
+      | null,
+  ) => void;
+  setTopBarSearchValue?: (value: string) => void;
+  setTopBarSearchLoading?: (loading: boolean) => void;
+
+  listTools(): Promise<ToolDescriptor[]>;
+  callTool<TResult = unknown>(name: string, args?: Record<string, unknown>): Promise<TResult>;
+
+  request(path: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+  }): Promise<unknown>;
+}