@notis_ai/cli 0.2.0-beta.19.1 → 0.2.0-beta.196.1

package/template/packages/notis-sdk/src/helpers.ts

@@ -1,131 +0,0 @@
-/**
- * Property extraction helpers for Notis DocumentRecord properties.
- *
- * Document properties come back in Notion-style nested shapes. These helpers
- * normalize them into simple JS values regardless of the shape.
- */
-
-import type { DocumentRecord } from './runtime';
-
-type Obj = Record<string, unknown>;
-
-/** Extract a string from a title, rich_text, or plain text property. */
-export function extractText(val: unknown): string {
-  if (typeof val === 'string') return val;
-  if (val && typeof val === 'object') {
-    const obj = val as Obj;
-    if (typeof obj.content === 'string') return obj.content;
-    if (typeof obj.plain_text === 'string') return obj.plain_text;
-    if (Array.isArray(obj.title)) {
-      return obj.title.map((t: Obj) => extractText(t?.text || t)).join('');
-    }
-    if (Array.isArray(obj.rich_text)) {
-      return obj.rich_text.map((t: Obj) => extractText(t?.text || t)).join('');
-    }
-    if (obj.text) return extractText(obj.text);
-  }
-  return '';
-}
-
-/** Extract a string from a select or status property. */
-export function extractSelect(val: unknown): string {
-  if (typeof val === 'string') return val;
-  if (val && typeof val === 'object') {
-    const obj = val as Obj;
-    if (obj.select && typeof obj.select === 'object') {
-      return (obj.select as Obj).name as string || '';
-    }
-    if (obj.status && typeof obj.status === 'object') {
-      return (obj.status as Obj).name as string || '';
-    }
-    if (typeof obj.name === 'string') return obj.name;
-  }
-  return '';
-}
-
-/** Extract a date string from a date property. */
-export function extractDate(val: unknown): string {
-  if (typeof val === 'string') return val;
-  if (val && typeof val === 'object') {
-    const obj = val as Obj;
-    if (obj.date && typeof obj.date === 'object') {
-      return (obj.date as Obj).start as string || '';
-    }
-    if (typeof obj.start === 'string') return obj.start;
-  }
-  return '';
-}
-
-/** Extract a number from a number property. */
-export function extractNumber(val: unknown): number | null {
-  if (typeof val === 'number') return val;
-  if (val && typeof val === 'object') {
-    const obj = val as Obj;
-    if (typeof obj.number === 'number') return obj.number;
-  }
-  return null;
-}
-
-/** Extract a boolean from a checkbox property. */
-export function extractCheckbox(val: unknown): boolean {
-  if (typeof val === 'boolean') return val;
-  if (val && typeof val === 'object') {
-    const obj = val as Obj;
-    if (typeof obj.checkbox === 'boolean') return obj.checkbox;
-  }
-  return false;
-}
-
-/** Extract multi-select values as a string array. */
-export function extractMultiSelect(val: unknown): string[] {
-  if (Array.isArray(val)) {
-    return val
-      .map((v) => {
-        if (typeof v === 'string') return v;
-        if (v && typeof v === 'object' && typeof (v as Obj).name === 'string') return (v as Obj).name as string;
-        return '';
-      })
-      .filter(Boolean);
-  }
-  if (val && typeof val === 'object') {
-    const obj = val as Obj;
-    if (Array.isArray(obj.multi_select)) return extractMultiSelect(obj.multi_select);
-  }
-  if (typeof val === 'string' && val) return [val];
-  return [];
-}
-
-/** Extract relation IDs from a relation property. */
-export function extractRelation(val: unknown): string[] {
-  if (Array.isArray(val)) {
-    return val
-      .map((v) => {
-        if (typeof v === 'string') return v;
-        if (v && typeof v === 'object' && typeof (v as Obj).id === 'string') return (v as Obj).id as string;
-        return '';
-      })
-      .filter(Boolean);
-  }
-  if (val && typeof val === 'object') {
-    const obj = val as Obj;
-    if (Array.isArray(obj.relation)) return extractRelation(obj.relation);
-  }
-  if (typeof val === 'string' && val) return [val];
-  return [];
-}
-
-/**
- * Extract display title from a document. Falls back through several property
- * names and shapes to find a human-readable title.
- */
-export function docTitle(doc: DocumentRecord): string {
-  const t = doc.title;
-  if (t && !/^[0-9a-f]{8}-[0-9a-f]{4}/.test(t)) return t;
-  const p = doc.properties || {};
-  const name = p.Name ?? p.name ?? p.Title ?? p.title;
-  if (name) {
-    const extracted = extractText(name);
-    if (extracted) return extracted;
-  }
-  return t || 'Untitled';
-}

package/template/packages/notis-sdk/src/hooks/useAppState.ts

@@ -1,50 +0,0 @@
-'use client';
-
-import { useCallback, useState } from 'react';
-import { useNotisRuntime } from '../provider';
-
-/**
- * Persist app-level state per user per app using localStorage.
- *
- * ```tsx
- * const [order, setOrder] = useAppState<string[]>('task-order', []);
- * ```
- *
- * State is scoped by `app.id` so different apps don't collide.
- * Falls back to defaultValue when localStorage is unavailable.
- */
-export function useAppState<T>(key: string, defaultValue: T): [T, (value: T | ((prev: T) => T)) => void] {
-  const runtime = useNotisRuntime();
-  const appId = runtime?.app?.id || '_unknown';
-  const storageKey = `notis-app-state:${appId}:${key}`;
-
-  const [value, setValueInternal] = useState<T>(() => {
-    if (typeof window === 'undefined') return defaultValue;
-    try {
-      const stored = localStorage.getItem(storageKey);
-      if (stored !== null) return JSON.parse(stored) as T;
-    } catch {
-      // Ignore parse errors or storage unavailable
-    }
-    return defaultValue;
-  });
-
-  const setValue = useCallback(
-    (newValue: T | ((prev: T) => T)) => {
-      setValueInternal((prev) => {
-        const resolved = typeof newValue === 'function'
-          ? (newValue as (prev: T) => T)(prev)
-          : newValue;
-        try {
-          localStorage.setItem(storageKey, JSON.stringify(resolved));
-        } catch {
-          // Ignore quota errors
-        }
-        return resolved;
-      });
-    },
-    [storageKey],
-  );
-
-  return [value, setValue];
-}

package/template/packages/notis-sdk/src/hooks/useCollectionItem.ts

@@ -1,58 +0,0 @@
-'use client';
-
-import { useEffect, useState } from 'react';
-import { useNotisRuntime } from '../provider';
-import type { CollectionItem } from '../runtime';
-
-interface UseCollectionResult {
-  /** Items in the collection (from the bound database). */
-  items: CollectionItem[];
-  loading: boolean;
-  error: Error | null;
-}
-
-/**
- * List collection items for the current route. Only meaningful on routes
- * that have a `collection` binding in `notis.config.ts`.
- *
- * ```tsx
- * const { items, loading } = useCollectionItems();
- * ```
- */
-export function useCollectionItems(): UseCollectionResult {
-  const runtime = useNotisRuntime();
-  const [items, setItems] = useState<CollectionItem[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  useEffect(() => {
-    if (!runtime) {
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-
-    runtime
-      .listCollectionItems()
-      .then((result) => {
-        if (!cancelled) {
-          setItems(result.items);
-          setLoading(false);
-        }
-      })
-      .catch((err) => {
-        if (!cancelled) {
-          setError(err instanceof Error ? err : new Error(String(err)));
-          setLoading(false);
-        }
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [runtime]);
-
-  return { items, loading, error };
-}

package/template/packages/notis-sdk/src/hooks/useDatabase.ts

@@ -1,87 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useState } from 'react';
-import { useNotisRuntime } from '../provider';
-import type { DocumentRecord, QueryFilter } from '../runtime';
-
-interface UseDatabaseOptions {
-  filter?: QueryFilter;
-  pageSize?: number;
-  offset?: number;
-  /** Set to false to skip the initial fetch. */
-  enabled?: boolean;
-}
-
-interface UseDatabaseResult {
-  documents: DocumentRecord[];
-  loading: boolean;
-  error: Error | null;
-  refetch: () => void;
-}
-
-/**
- * Query documents from a Notis database owned by this app.
- *
- * ```tsx
- * const { documents, loading } = useDatabase('transactions', {
- *   filter: { sorts: [{ property: 'date', direction: 'desc' }] },
- *   pageSize: 20,
- * });
- * ```
- */
-export function useDatabase(
-  databaseSlug: string,
-  options: UseDatabaseOptions = {},
-): UseDatabaseResult {
-  const runtime = useNotisRuntime();
-  const [documents, setDocuments] = useState<DocumentRecord[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
-  const enabled = options.enabled !== false;
-
-  const refetch = useCallback(() => {
-    setFetchKey((k) => k + 1);
-  }, []);
-
-  useEffect(() => {
-    if (!runtime || !enabled) {
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
-
-    runtime
-      .queryDatabase({
-        databaseSlug,
-        query: {
-          ...options.filter,
-          page_size: options.pageSize,
-        },
-        offset: options.offset,
-      })
-      .then((result) => {
-        if (!cancelled) {
-          setDocuments(result.documents);
-          setLoading(false);
-        }
-      })
-      .catch((err) => {
-        if (!cancelled) {
-          setError(err instanceof Error ? err : new Error(String(err)));
-          setLoading(false);
-        }
-      });
-
-    return () => {
-      cancelled = true;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [runtime, databaseSlug, fetchKey, enabled]);
-
-  return { documents, loading, error, refetch };
-}

package/template/packages/notis-sdk/src/hooks/useDocument.ts

@@ -1,61 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useState } from 'react';
-import { useNotisRuntime } from '../provider';
-import type { DocumentRecord } from '../runtime';
-
-interface UseDocumentResult {
-  document: DocumentRecord | null;
-  loading: boolean;
-  error: Error | null;
-  refetch: () => void;
-}
-
-/**
- * Fetch a single document by ID.
- *
- * ```tsx
- * const { document, loading } = useDocument(documentId);
- * ```
- */
-export function useDocument(documentId: string | null | undefined): UseDocumentResult {
-  const runtime = useNotisRuntime();
-  const [document, setDocument] = useState<DocumentRecord | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
-
-  useEffect(() => {
-    if (!runtime || !documentId) {
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
-
-    runtime
-      .getDocument({ documentId })
-      .then((result) => {
-        if (!cancelled) {
-          setDocument(result);
-          setLoading(false);
-        }
-      })
-      .catch((err) => {
-        if (!cancelled) {
-          setError(err instanceof Error ? err : new Error(String(err)));
-          setLoading(false);
-        }
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [runtime, documentId, fetchKey]);
-
-  return { document, loading, error, refetch };
-}

package/template/packages/notis-sdk/src/hooks/useNotis.ts

@@ -1,31 +0,0 @@
-'use client';
-
-import { useNotisRuntime } from '../provider';
-import type { AppDescriptor, RouteDescriptor, DatabaseDescriptor } from '../runtime';
-
-interface NotisContext {
-  /** App metadata (id, name, icon, description). Null before runtime loads. */
-  app: AppDescriptor | null;
-  /** Current route descriptor. Null before runtime loads. */
-  route: RouteDescriptor | null;
-  /** Databases declared by this app. Empty before runtime loads. */
-  databases: DatabaseDescriptor[];
-  /** Whether the runtime is loaded and available. */
-  ready: boolean;
-}
-
-/**
- * Access app-level metadata: the app descriptor, current route, and declared
- * databases. Returns safe defaults when the runtime isn't available (SSR or
- * during `next dev` without preview).
- */
-export function useNotis(): NotisContext {
-  const runtime = useNotisRuntime();
-
-  return {
-    app: runtime?.app ?? null,
-    route: runtime?.route ?? null,
-    databases: runtime?.databases ?? [],
-    ready: runtime !== null,
-  };
-}

package/template/packages/notis-sdk/src/hooks/useNotisNavigation.ts

@@ -1,49 +0,0 @@
-'use client';
-
-import { useCallback } from 'react';
-import { useNotisRuntime } from '../provider';
-
-interface NavigationActions {
-  /** Navigate to a route within the app by its path. */
-  toRoute: (path: string) => void;
-  /** Navigate to a document detail view. */
-  toDocument: (documentId: string) => void;
-  /** Navigate to the app's default route. */
-  toApp: () => void;
-}
-
-/**
- * Navigation helpers for moving between routes and documents within the app.
- * When rendered inside the portal, uses the runtime.navigate() bridge.
- * In local preview, falls back to window.location.
- *
- * ```tsx
- * const nav = useNotisNavigation();
- * nav.toRoute('/settings');
- * ```
- */
-export function useNotisNavigation(): NavigationActions {
-  const runtime = useNotisRuntime();
-
-  const toRoute = useCallback((path: string) => {
-    if (runtime?.navigate) {
-      runtime.navigate({ kind: 'route', path });
-    } else if (typeof window !== 'undefined') {
-      window.location.href = path;
-    }
-  }, [runtime]);
-
-  const toDocument = useCallback((documentId: string) => {
-    if (runtime?.navigate) {
-      runtime.navigate({ kind: 'document', documentId });
-    }
-  }, [runtime]);
-
-  const toApp = useCallback(() => {
-    if (runtime?.navigate) {
-      runtime.navigate({ kind: 'app' });
-    }
-  }, [runtime]);
-
-  return { toRoute, toDocument, toApp };
-}

package/template/packages/notis-sdk/src/hooks/useTool.ts

@@ -1,49 +0,0 @@
-'use client';
-
-import { useCallback, useState } from 'react';
-import { useNotisRuntime } from '../provider';
-
-interface UseToolResult {
-  call: (args?: Record<string, unknown>) => Promise<unknown>;
-  loading: boolean;
-  error: Error | null;
-}
-
-/**
- * Call a specific Notis tool by name.
- *
- * ```tsx
- * const { call, loading } = useTool('notis_web_search');
- * const result = await call({ query: 'latest news' });
- * ```
- */
-export function useTool(toolName: string): UseToolResult {
-  const runtime = useNotisRuntime();
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  const call = useCallback(
-    async (args?: Record<string, unknown>): Promise<unknown> => {
-      if (!runtime) {
-        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
-      }
-
-      setLoading(true);
-      setError(null);
-
-      try {
-        const result = await runtime.callTool(toolName, args);
-        return result;
-      } catch (err) {
-        const e = err instanceof Error ? err : new Error(String(err));
-        setError(e);
-        throw e;
-      } finally {
-        setLoading(false);
-      }
-    },
-    [runtime, toolName],
-  );
-
-  return { call, loading, error };
-}

package/template/packages/notis-sdk/src/hooks/useUpsertDocument.ts

@@ -1,57 +0,0 @@
-'use client';
-
-import { useCallback, useState } from 'react';
-import { useNotisRuntime } from '../provider';
-import type { DocumentRecord } from '../runtime';
-
-interface UpsertArgs {
-  databaseSlug: string;
-  documentId?: string;
-  title?: string;
-  properties?: Record<string, unknown>;
-}
-
-interface UseUpsertDocumentResult {
-  upsert: (args: UpsertArgs) => Promise<DocumentRecord>;
-  loading: boolean;
-  error: Error | null;
-}
-
-/**
- * Create or update a document in a Notis database.
- *
- * ```tsx
- * const { upsert, loading } = useUpsertDocument();
- * await upsert({ databaseSlug: 'tasks', title: 'New task', properties: { status: 'Open' } });
- * ```
- */
-export function useUpsertDocument(): UseUpsertDocumentResult {
-  const runtime = useNotisRuntime();
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  const upsert = useCallback(
-    async (args: UpsertArgs): Promise<DocumentRecord> => {
-      if (!runtime) {
-        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
-      }
-
-      setLoading(true);
-      setError(null);
-
-      try {
-        const result = await runtime.upsertDocument(args);
-        return result.document;
-      } catch (err) {
-        const e = err instanceof Error ? err : new Error(String(err));
-        setError(e);
-        throw e;
-      } finally {
-        setLoading(false);
-      }
-    },
-    [runtime],
-  );
-
-  return { upsert, loading, error };
-}

package/template/packages/notis-sdk/src/index.ts

@@ -1,47 +0,0 @@
-/**
- * @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 { useDatabase } from './hooks/useDatabase';
-export { useDocument } from './hooks/useDocument';
-export { useUpsertDocument } from './hooks/useUpsertDocument';
-export { useTool } from './hooks/useTool';
-export { useTools } from './hooks/useTools';
-export { useCollectionItems } from './hooks/useCollectionItem';
-export { useNotisNavigation } from './hooks/useNotisNavigation';
-export { useBackend } from './hooks/useBackend';
-export { useAppState } from './hooks/useAppState';
-
-// Property extraction helpers
-export {
-  extractText,
-  extractSelect,
-  extractDate,
-  extractNumber,
-  extractCheckbox,
-  extractMultiSelect,
-  extractRelation,
-  docTitle,
-} from './helpers';
-
-// Types (re-exported for convenience)
-export type {
-  AppDescriptor,
-  CollectionItem,
-  DatabaseDescriptor,
-  DatabaseProperty,
-  DocumentRecord,
-  NotisRuntime,
-  QueryFilter,
-  RouteDescriptor,
-  ToolDescriptor,
-} from './runtime';

package/template/packages/notis-sdk/src/provider.tsx

@@ -1,44 +0,0 @@
-'use client';
-
-import React, { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
-import type { NotisRuntime } from './runtime';
-import { getRuntime } from './runtime';
-
-const NotisContext = createContext<NotisRuntime | null>(null);
-
-/**
- * Provides the Notis runtime context to all child components. Place this in
- * your root layout so that hooks like useDatabase, useTool, etc. can access
- * the platform bridge.
- *
- * During `next dev` (no runtime injected), hooks return safe defaults (empty
- * arrays, null values). During `notis apps preview` and in the portal, the
- * runtime is fully functional.
- */
-export function NotisProvider({ children, runtime }: { children: ReactNode; runtime?: NotisRuntime | null }) {
-  const [resolvedRuntime, setResolvedRuntime] = useState<NotisRuntime | null>(runtime ?? null);
-
-  useEffect(() => {
-    // If runtime was passed as a prop (portal component rendering), use it directly.
-    // Otherwise fall back to window.__NOTIS_RUNTIME__ (local dev / preview).
-    if (runtime !== undefined) {
-      setResolvedRuntime(runtime);
-    } else {
-      setResolvedRuntime(getRuntime());
-    }
-  }, [runtime]);
-
-  return (
-    <NotisContext.Provider value={resolvedRuntime}>
-      {children}
-    </NotisContext.Provider>
-  );
-}
-
-/**
- * Returns the raw NotisRuntime or null if not yet available.
- * Prefer the typed hooks (useDatabase, useTool, etc.) over this.
- */
-export function useNotisRuntime(): NotisRuntime | null {
-  return useContext(NotisContext);
-}