@notis_ai/cli 0.2.0-beta.102.1

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

@@ -0,0 +1,145 @@
+/**
+ * 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: 'phosphor:squares-four',
+ *   databases: ['tasks'],
+ *   routes: [
+ *     {
+ *       path: '/',
+ *       slug: 'notes',
+ *       name: 'Notes',
+ *       default: true,
+ *       collection: {
+ *         database: 'notes',
+ *         titleProperty: 'Name',
+ *         parentProperty: 'Parent',
+ *         sidebar: {
+ *           mode: 'tree',
+ *           allowCreate: true,
+ *         },
+ *       },
+ *     },
+ *   ],
+ *   tools: [...],
+ * });
+ * ```
+ */
+
+export interface NotisRouteConfig {
+  path: string;
+  slug: string;
+  name: string;
+  icon?: string;
+  parentSlug?: string | null;
+  default?: boolean;
+  exportName?: string;
+  collection?: {
+    database: string;
+    titleProperty: string;
+    parentProperty?: string | null;
+    sidebar?: {
+      mode: 'flat-list' | 'tree';
+      allowCreate: boolean;
+    };
+  };
+}
+
+export const NOTIS_APP_CATEGORIES = [
+  'Productivity',
+  'Sales & Marketing',
+  'Operations',
+  'Product & Engineering',
+  'Personal',
+] as const;
+
+export type NotisAppCategory = typeof NOTIS_APP_CATEGORIES[number];
+
+export interface NotisAppAuthor {
+  name: string;
+  handle?: string;
+  url?: string;
+}
+
+export interface NotisAppSkillConfig {
+  key: string;
+  path: string;
+  name: string;
+  description?: string;
+}
+
+export interface NotisAppOnboardingConfig {
+  skill: string;
+  prompt: string;
+}
+
+export interface NotisAppScreenshotConfig {
+  path: string;
+  alt: string;
+  route?: string;
+  scenario?: string;
+  focus?: string;
+  theme?: 'light' | 'dark';
+}
+
+/**
+ * Named accent tokens for an app's avatar. Keep in sync with the portal
+ * `ACCENT_NAMES` and the server `ACCENT_TOKENS`.
+ */
+export const NOTIS_APP_ACCENTS = [
+  'blue',
+  'violet',
+  'emerald',
+  'amber',
+  'rose',
+  'sky',
+  'fuchsia',
+  'teal',
+] as const;
+
+export type NotisAppAccent = typeof NOTIS_APP_ACCENTS[number];
+
+export interface NotisAppConfig {
+  /** URL-safe app slug. Existing apps may still use a display name here. */
+  name: string;
+  /** Human display title, Raycast-style. Falls back to `name`. */
+  title?: string;
+  description?: string;
+  /**
+   * App icon. A `phosphor:<name>` value (e.g. `phosphor:dice-five`) or
+   * `metadata/icon.png`. When unset, the app shows its two-letter initials.
+   */
+  icon?: string;
+  /**
+   * Optional accent color for the app avatar. One of {@link NOTIS_APP_ACCENTS}.
+   * When unset, a stable accent is derived automatically from the app id.
+   */
+  accent?: NotisAppAccent;
+  author?: NotisAppAuthor;
+  categories?: NotisAppCategory[];
+  tagline?: string;
+  /** @deprecated Add release entries to the root CHANGELOG.md instead. */
+  versionNotes?: string;
+  screenshots?: NotisAppScreenshotConfig[];
+  databases?: string[];
+  routes?: NotisRouteConfig[];
+  tools?: string[];
+  skills?: NotisAppSkillConfig[];
+  onboarding?: NotisAppOnboardingConfig;
+}
+
+/**
+ * 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/sdk/src/documents.ts

@@ -0,0 +1,229 @@
+/**
+ * Document data helpers: normalize raw tool results (Notion-shaped property
+ * values, snake_case fields) into the SDK's `DocumentRecord`/`DatabaseProperty`
+ * shapes, and derive plain-text projections from typed content.
+ *
+ * These are pure functions — safe in any context (portal, dev harness, tests).
+ */
+
+import type {
+  DatabaseProperty,
+  DatabasePropertyOption,
+  DatabasePropertyType,
+  DocumentContentType,
+  DocumentRecord,
+} from './runtime';
+
+// ---------------------------------------------------------------------------
+// Value primitives
+// ---------------------------------------------------------------------------
+
+export function isPresentString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+export function optionalString(value: unknown): string | null {
+  return isPresentString(value) ? value.trim() : null;
+}
+
+/** Flattens a Notion-shaped rich_text array (or plain string) to text. */
+export function extractRichText(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (!Array.isArray(value)) return '';
+  return value
+    .map((item) => {
+      const record = asRecord(item);
+      const text = asRecord(record?.text);
+      return optionalString(text?.content) ?? optionalString(record?.plain_text) ?? '';
+    })
+    .join('');
+}
+
+/** Extracts the ids of a normalized relation property value. */
+export function getRelationIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => isPresentString(item));
+}
+
+// ---------------------------------------------------------------------------
+// Property + document normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Collapses a Notion-shaped property value ({type: 'select', select: {...}})
+ * into a plain JS value (string, string[], number, boolean, ...). Values that
+ * are already plain pass through unchanged.
+ */
+export function normalizePropertyValue(value: unknown): unknown {
+  const record = asRecord(value);
+  if (!record) return value;
+
+  const type = optionalString(record.type);
+  if (!type) return value;
+
+  if (type === 'title') return extractRichText(record.title);
+  if (type === 'rich_text') return extractRichText(record.rich_text);
+  if (type === 'select' || type === 'status') {
+    return optionalString(asRecord(record[type])?.name) ?? record[type] ?? null;
+  }
+  if (type === 'multi_select') {
+    const items = Array.isArray(record.multi_select) ? record.multi_select : [];
+    return items.map((item) => optionalString(asRecord(item)?.name) ?? item).filter(Boolean);
+  }
+  if (type === 'relation') {
+    const items = Array.isArray(record.relation) ? record.relation : [];
+    return items.map((item) => optionalString(asRecord(item)?.id) ?? item).filter(Boolean);
+  }
+  if (type === 'date') return optionalString(asRecord(record.date)?.start) ?? record.date ?? null;
+  if (type in record) return record[type];
+  return value;
+}
+
+function normalizeContentType(value: unknown): DocumentContentType | null {
+  return value === 'markdown' || value === 'file' ? value : null;
+}
+
+/**
+ * Normalizes a raw document from a Notis database tool result
+ * (LOCAL_NOTIS_DATABASE_QUERY / GET_DOCUMENT / UPSERT_*) into a
+ * `DocumentRecord`: camelCases fields and collapses property values.
+ */
+export function normalizeDocumentRecord(value: unknown): DocumentRecord {
+  const record = asRecord(value) ?? {};
+  const rawProperties = asRecord(record.properties) ?? {};
+  const properties: Record<string, unknown> = {};
+  for (const [key, propertyValue] of Object.entries(rawProperties)) {
+    properties[key] = normalizePropertyValue(propertyValue);
+  }
+
+  return {
+    id: optionalString(record.id) ?? '',
+    title: optionalString(record.title) ?? 'Untitled',
+    url: optionalString(record.url),
+    properties,
+    icon: optionalString(record.icon),
+    cover: optionalString(record.cover),
+    databaseSlug: optionalString(record.databaseSlug) ?? optionalString(record.database_slug) ?? undefined,
+    contentType: normalizeContentType(record.contentType ?? record.content_type),
+    fileType: optionalString(record.fileType) ?? optionalString(record.file_type),
+    contentBlocknote: Array.isArray(record.contentBlocknote)
+      ? (record.contentBlocknote as Array<Record<string, unknown>>)
+      : Array.isArray(record.content_blocknote)
+        ? (record.content_blocknote as Array<Record<string, unknown>>)
+        : null,
+    contentMarkdown: optionalString(record.contentMarkdown) ?? optionalString(record.content_markdown),
+    plainText: optionalString(record.plainText) ?? optionalString(record.plain_text),
+    createdAt:
+      optionalString(record.createdAt)
+      ?? optionalString(record.created_at)
+      ?? optionalString(record.created_time),
+    lastEditedTime:
+      optionalString(record.lastEditedTime)
+      ?? optionalString(record.last_edited_time)
+      ?? optionalString(record.updated_at),
+  };
+}
+
+/** Normalizes a raw schema property from LOCAL_NOTIS_DATABASE_GET_DATABASE. */
+export function normalizeDatabaseProperty(value: unknown): DatabaseProperty | null {
+  const record = asRecord(value);
+  const name = optionalString(record?.name);
+  if (!record || !name) return null;
+
+  const rawOptions = Array.isArray(record.options) ? record.options : [];
+  const options = rawOptions.flatMap((option): DatabasePropertyOption[] => {
+    const optionRecord = asRecord(option);
+    const optionName = optionalString(optionRecord?.name);
+    if (!optionRecord || !optionName) return [];
+    return [{
+      id: optionalString(optionRecord.id),
+      name: optionName,
+      color: optionalString(optionRecord.color),
+      order: typeof optionRecord.order === 'number' ? optionRecord.order : undefined,
+    }];
+  });
+
+  return {
+    id: optionalString(record.id),
+    name,
+    type: (optionalString(record.type) ?? 'rich_text') as DatabasePropertyType,
+    description: optionalString(record.description),
+    options,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Plain-text projections
+// ---------------------------------------------------------------------------
+
+/** Strips markdown syntax to readable plain text (previews, search). */
+export function markdownToPlainText(markdown: string): string {
+  return markdown
+    // fenced code blocks: keep the code, drop the fences
+    .replace(/```[^\n]*\n?/g, '')
+    // images: keep alt text
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+    // links: keep link text
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    // html tags
+    .replace(/<[^>]+>/g, ' ')
+    // headings, blockquotes, list markers, task boxes
+    .replace(/^\s{0,3}(#{1,6}\s+|>\s?|[-*+]\s+(\[[ xX]\]\s+)?|\d+\.\s+)/gm, '')
+    // emphasis / strikethrough / inline code
+    .replace(/(\*\*|__|[*_~`])/g, '')
+    // table separators and pipes
+    .replace(/^\s*\|?[-:| ]+\|?\s*$/gm, '')
+    .replace(/\|/g, ' ')
+    // horizontal rules
+    .replace(/^\s*([-*_]\s*){3,}$/gm, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** Flattens BlockNote block JSON to plain text. */
+export function blockNoteToPlainText(blocks: unknown): string {
+  const segments: string[] = [];
+
+  function visit(node: unknown): void {
+    if (typeof node === 'string') {
+      if (node.trim()) segments.push(node.trim());
+      return;
+    }
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    const record = asRecord(node);
+    if (!record) return;
+    if (typeof record.text === 'string' && record.text.trim()) {
+      segments.push(record.text.trim());
+    }
+    visit(record.content);
+    visit(record.children);
+  }
+
+  visit(blocks);
+  return segments.join(' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Best-available plain-text preview for a document:
+ * plainText -> contentMarkdown -> contentBlocknote -> title.
+ */
+export function getDocumentPreview(document: DocumentRecord): string {
+  if (isPresentString(document.plainText)) {
+    return document.plainText.replace(/\s+/g, ' ').trim();
+  }
+  if (isPresentString(document.contentMarkdown)) {
+    return markdownToPlainText(document.contentMarkdown);
+  }
+  const fromBlocks = blockNoteToPlainText(document.contentBlocknote);
+  if (fromBlocks) return fromBlocks;
+  return isPresentString(document.title) ? document.title : 'Untitled';
+}

package/template/packages/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/sdk/src/hooks/useDatabaseSchema.ts

@@ -0,0 +1,85 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDatabaseProperty, optionalString } from '../documents';
+import type { DatabaseProperty } from '../runtime';
+
+interface GetDatabaseResult {
+  database?: {
+    name?: string;
+    description?: string | null;
+    schema?: {
+      properties?: unknown[];
+    };
+  };
+  message?: string;
+  error?: string;
+}
+
+export interface UseDatabaseSchemaResult {
+  name: string | null;
+  description: string | null;
+  properties: DatabaseProperty[];
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/** Fetch a database's schema (normalized properties + metadata). */
+export function useDatabaseSchema(databaseSlug: string): UseDatabaseSchemaResult {
+  const runtime = useNotisRuntime();
+  const [name, setName] = useState<string | null>(null);
+  const [description, setDescription] = useState<string | null>(null);
+  const [properties, setProperties] = useState<DatabaseProperty[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const refetch = useCallback(() => {
+    setFetchKey((key) => key + 1);
+  }, []);
+
+  useEffect(() => {
+    if (!runtime) {
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+
+    runtime
+      .callTool<GetDatabaseResult>('LOCAL_NOTIS_DATABASE_GET_DATABASE', {
+        database_slug: databaseSlug,
+      })
+      .then((result) => {
+        if (cancelled) return;
+        const message = result.error ?? result.message;
+        if (!result.database && message) {
+          throw new Error(message);
+        }
+        setName(optionalString(result.database?.name));
+        setDescription(optionalString(result.database?.description));
+        const rawProperties = result.database?.schema?.properties ?? [];
+        setProperties(
+          rawProperties
+            .map(normalizeDatabaseProperty)
+            .filter((property): property is DatabaseProperty => Boolean(property)),
+        );
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime, databaseSlug, fetchKey]);
+
+  return { name, description, properties, loading, error, refetch };
+}

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

@@ -0,0 +1,78 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord } from '../runtime';
+
+interface GetDocumentResult {
+  status?: string;
+  document?: unknown;
+  message?: string;
+  error?: string;
+}
+
+export interface UseDocumentOptions {
+  enabled?: boolean;
+}
+
+export interface UseDocumentResult {
+  document: DocumentRecord | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/** Fetch a single document (with content) by id, normalized. */
+export function useDocument(
+  documentId: string | null | undefined,
+  options: UseDocumentOptions = {},
+): UseDocumentResult {
+  const runtime = useNotisRuntime();
+  const [document, setDocument] = useState<DocumentRecord | null>(null);
+  const [loading, setLoading] = useState(Boolean(documentId));
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const enabled = options.enabled !== false && Boolean(documentId);
+
+  const refetch = useCallback(() => {
+    setFetchKey((key) => key + 1);
+  }, []);
+
+  useEffect(() => {
+    if (!runtime || !enabled || !documentId) {
+      setDocument(null);
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+
+    runtime
+      .callTool<GetDocumentResult>('LOCAL_NOTIS_DATABASE_GET_DOCUMENT', {
+        document_id: documentId,
+      })
+      .then((result) => {
+        if (cancelled) return;
+        if (!result.document) {
+          throw new Error(result.error ?? result.message ?? 'Document not found');
+        }
+        setDocument(normalizeDocumentRecord(result.document));
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime, documentId, enabled, fetchKey]);
+
+  return { document, loading, error, refetch };
+}

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

@@ -0,0 +1,121 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord, QueryFilter } from '../runtime';
+
+interface QueryDatabaseResult {
+  documents?: unknown[];
+  has_more?: boolean;
+  next_offset?: number | null;
+  message?: string;
+  error?: string;
+}
+
+export interface UseDocumentsOptions {
+  filter?: QueryFilter;
+  pageSize?: number;
+  offset?: number;
+  /** Fetch every page, starting at offset, instead of returning only one page. */
+  fetchAll?: boolean;
+  enabled?: boolean;
+}
+
+export interface UseDocumentsResult {
+  documents: DocumentRecord[];
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/**
+ * Query a Notis database and get normalized `DocumentRecord`s.
+ *
+ * ```tsx
+ * const { documents, loading, refetch } = useDocuments('notes', {
+ *   filter: { filters: [{ property: 'Folder', operator: 'contains', type: 'relation', value: folderId }] },
+ *   pageSize: 250,
+ * });
+ * ```
+ */
+export function useDocuments(
+  databaseSlug: string,
+  options: UseDocumentsOptions = {},
+): UseDocumentsResult {
+  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 filterKey = JSON.stringify(options.filter ?? null);
+
+  const refetch = useCallback(() => {
+    setFetchKey((key) => key + 1);
+  }, []);
+
+  useEffect(() => {
+    if (!runtime || !enabled) {
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+
+    const filter = filterKey === 'null' ? null : (JSON.parse(filterKey) as QueryFilter);
+
+    const fetchDocuments = async (): Promise<unknown[]> => {
+      const allDocuments: unknown[] = [];
+      let offset = options.offset ?? 0;
+
+      while (true) {
+        const result = await runtime.callTool<QueryDatabaseResult>('LOCAL_NOTIS_DATABASE_QUERY', {
+          database_slug: databaseSlug,
+          query: {
+            ...(filter ?? {}),
+            ...(options.pageSize !== undefined ? { page_size: options.pageSize } : {}),
+          },
+          ...(offset > 0 ? { offset } : {}),
+        });
+        const message = result.error ?? result.message;
+        if (!result.documents && message) {
+          throw new Error(message);
+        }
+        allDocuments.push(...(result.documents ?? []));
+        if (!options.fetchAll || !result.has_more) return allDocuments;
+
+        const nextOffset = result.next_offset;
+        if (typeof nextOffset !== 'number' || nextOffset <= offset) {
+          throw new Error('Database query returned an invalid pagination offset');
+        }
+        offset = nextOffset;
+      }
+    };
+
+    fetchDocuments()
+      .then((result) => {
+        if (cancelled) return;
+        setDocuments(
+          result
+            .map(normalizeDocumentRecord)
+            .filter((document) => document.id),
+        );
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime, databaseSlug, enabled, fetchKey, filterKey, options.fetchAll, options.offset, options.pageSize]);
+
+  return { documents, loading, error, refetch };
+}