@notis_ai/cli 0.2.0-beta.16.1

package/template/packages/notis-sdk/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@notis/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./config": "./src/config.ts",
+    "./vite": "./src/vite.ts",
+    "./ui": "./src/ui.ts",
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "src",
+    "template"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "vite": ">=5.0.0",
+    "@vitejs/plugin-react": ">=4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Configuration utilities for notis.config.ts.
+ *
+ * Usage:
+ * ```ts
+ * // notis.config.ts
+ * import { defineNotisApp } from '@notis/sdk/config';
+ *
+ * export default defineNotisApp({
+ *   name: 'My App',
+ *   description: 'Does things',
+ *   icon: 'lucide:layout-dashboard',
+ *   databases: ['tasks'],
+ *   routes: [...],
+ *   tools: [...],
+ * });
+ * ```
+ */
+
+export interface NotisRouteConfig {
+  path: string;
+  name: string;
+  icon?: string;
+  default?: boolean;
+  exportName?: string;
+  collection?: {
+    database: string;
+    titleProperty: string;
+  };
+}
+
+export interface NotisAppConfig {
+  name: string;
+  description?: string;
+  icon?: string;
+  databases?: string[];
+  routes?: NotisRouteConfig[];
+  tools?: string[];
+}
+
+/**
+ * Identity function that provides type checking and autocomplete for the
+ * Notis app configuration. The returned object is read at build time by
+ * `notis apps build` to generate the manifest.
+ */
+export function defineNotisApp(config: NotisAppConfig): NotisAppConfig {
+  return config;
+}

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

@@ -0,0 +1,131 @@
+/**
+ * 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

@@ -0,0 +1,50 @@
+'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/useBackend.ts

@@ -0,0 +1,41 @@
+'use client';
+
+import { useCallback } from 'react';
+import { useNotisRuntime } from '../provider';
+
+interface UseBackendResult {
+  /**
+   * Make an authenticated request to the Notis backend.
+   * The path should be an absolute backend path (e.g. `/portal_composio/actions`).
+   */
+  request: (path: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+  }) => Promise<unknown>;
+}
+
+/**
+ * Raw backend request proxy. Use this for custom server endpoints or
+ * integration APIs not covered by the typed hooks.
+ *
+ * ```tsx
+ * const { request } = useBackend();
+ * const data = await request('/portal_composio/actions', { method: 'POST', body: { ... } });
+ * ```
+ */
+export function useBackend(): UseBackendResult {
+  const runtime = useNotisRuntime();
+
+  const request = useCallback(
+    async (path: string, options?: { method?: string; headers?: Record<string, string>; body?: unknown }) => {
+      if (!runtime) {
+        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
+      }
+      return runtime.request(path, options);
+    },
+    [runtime],
+  );
+
+  return { request };
+}

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

@@ -0,0 +1,58 @@
+'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

@@ -0,0 +1,87 @@
+'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

@@ -0,0 +1,61 @@
+'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

@@ -0,0 +1,31 @@
+'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

@@ -0,0 +1,49 @@
+'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

@@ -0,0 +1,49 @@
+'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/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 };
+}