@qwanyx/stack 0.2.2 → 0.2.3

package/dist/api/client.d.ts

@@ -0,0 +1,53 @@
+import type { ApiConfig, QueryParams } from '../types';
+/**
+ * Generic API Client
+ * Framework-agnostic HTTP client for any API
+ */
+export declare class ApiClient {
+    private config;
+    constructor(config: ApiConfig);
+    /**
+     * Build query string from params
+     */
+    private buildQueryString;
+    /**
+     * Make HTTP request
+     */
+    private request;
+    /**
+     * GET request
+     */
+    get<T = any>(endpoint: string, params?: QueryParams): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T = any>(endpoint: string, body?: any, params?: QueryParams): Promise<T>;
+    /**
+     * PUT request
+     */
+    put<T = any>(endpoint: string, body?: any, params?: QueryParams): Promise<T>;
+    /**
+     * PATCH request
+     */
+    patch<T = any>(endpoint: string, body?: any, params?: QueryParams): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T = any>(endpoint: string, params?: QueryParams): Promise<T>;
+    /**
+     * Update base URL
+     */
+    setBaseUrl(baseUrl: string): void;
+    /**
+     * Get current base URL
+     */
+    getBaseUrl(): string;
+}
+/**
+ * Initialize the API client
+ */
+export declare function initializeApiClient(config: ApiConfig): ApiClient;
+/**
+ * Get the API client instance
+ */
+export declare function getApiClient(): ApiClient;

package/dist/auth/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Generic authentication manager
+ * Handles token storage and retrieval
+ */
+export declare class AuthManager {
+    /**
+     * Store authentication token
+     */
+    static setToken(token: string): void;
+    /**
+     * Get authentication token
+     */
+    static getToken(): string | null;
+    /**
+     * Remove authentication token
+     */
+    static clearToken(): void;
+    /**
+     * Store refresh token
+     */
+    static setRefreshToken(token: string): void;
+    /**
+     * Get refresh token
+     */
+    static getRefreshToken(): string | null;
+    /**
+     * Check if user is authenticated
+     */
+    static isAuthenticated(): boolean;
+    /**
+     * Get authorization header
+     */
+    static getAuthHeader(): Record<string, string>;
+}

package/dist/client/GraphClient.d.ts

@@ -0,0 +1,86 @@
+/**
+ * GraphClient - Backend Communication Layer
+ *
+ * Provides a type-safe interface to the qwanyx-brain SPU backend.
+ * All operations communicate through the unified `/spu/invoke` endpoint.
+ */
+import type { GraphNode, GraphEdge, GraphClientConfig } from '../types';
+export declare class GraphClient {
+    private config;
+    constructor(config: GraphClientConfig);
+    /**
+     * Call the Graph coprocessor
+     */
+    private callGraph;
+    /**
+     * Get auth token from localStorage (browser) or return empty string
+     */
+    private getToken;
+    /**
+     * Get children nodes
+     */
+    getChildren(parentId?: string): Promise<GraphNode[]>;
+    /**
+     * Get a specific node by ID
+     */
+    getNode(nodeId: string): Promise<GraphNode | null>;
+    /**
+     * Add a new node
+     */
+    addNode(node: Partial<GraphNode> & {
+        p?: string;
+        type: string;
+    }): Promise<GraphNode>;
+    /**
+     * Update an existing node
+     */
+    updateNode(nodeId: string, updates: Partial<GraphNode>): Promise<GraphNode>;
+    /**
+     * Delete a node
+     */
+    deleteNode(nodeId: string, cascade?: boolean): Promise<boolean>;
+    /**
+     * Get children with edges (supports different display modes)
+     */
+    getChildrenWithEdges(nodeId?: string, displayMode?: 'children' | 'edges' | 'both', edgeType?: string, nodeType?: string): Promise<GraphNode[]>;
+    /**
+     * Add an edge between two nodes
+     */
+    addEdge(sourceId: string | null, targetId: string, edgeType?: string, data?: Record<string, any>): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Delete an edge
+     */
+    deleteEdge(sourceId: string | null, targetId: string, edgeType?: string): Promise<{
+        deleted: boolean;
+        count: number;
+    }>;
+    /**
+     * Get edges from a source node
+     * @param sourceId - Source node ID (null for edges without source)
+     * @param edgeType - Optional edge type filter
+     * @param targetId - Optional target node ID for reverse lookups
+     */
+    getEdges(sourceId: string | null, edgeType?: string, targetId?: string): Promise<GraphEdge[]>;
+    /**
+     * Get ancestors of a node (path from root to node)
+     */
+    getAncestors(nodeId: string): Promise<GraphNode[]>;
+    /**
+     * Get tree structure starting from a root
+     */
+    getTree(rootId?: string, maxDepth?: number): Promise<any>;
+    /**
+     * Move a node to a new parent
+     */
+    moveNode(nodeId: string, newParentId?: string): Promise<GraphNode>;
+    /**
+     * Search nodes by query
+     */
+    searchNodes(query: string, type?: string): Promise<GraphNode[]>;
+    /**
+     * Get all nodes of a specific type
+     */
+    getNodesByType(type: string): Promise<GraphNode[]>;
+}

package/dist/client/MailClient.d.ts

@@ -0,0 +1,69 @@
+/**
+ * MailClient - Email Communication Layer
+ *
+ * Provides a type-safe interface to the mail coprocessor in qwanyx-brain.
+ * Handles email settings (with encrypted passwords) and IMAP operations.
+ */
+import type { MailClientConfig, MailAccount, MailListResult, ImapResponse, FolderInfo } from '../types';
+export declare class MailClient {
+    private config;
+    constructor(config: MailClientConfig);
+    /**
+     * Call the Mail coprocessor
+     */
+    private callMail;
+    /**
+     * Get auth token from localStorage (browser) or return empty string
+     */
+    private getToken;
+    /**
+     * Get email settings with decrypted passwords
+     */
+    getSettings(): Promise<{
+        accounts: MailAccount[];
+    }>;
+    /**
+     * Save email settings (passwords encrypted server-side)
+     */
+    saveSettings(accounts: MailAccount[]): Promise<void>;
+    /**
+     * List emails from IMAP inbox
+     */
+    listEmails(accountId?: string, limit?: number): Promise<MailListResult>;
+    /**
+     * Delete emails by UID
+     */
+    deleteEmails(accountId: string, uids: number[], expunge?: boolean): Promise<{
+        success: boolean;
+        deleted: number;
+    }>;
+    /**
+     * Execute raw IMAP commands - thin proxy for stack-side logic
+     * Commands are strings like: "SELECT INBOX", "UID STORE 123 +FLAGS (\\Deleted)", "EXPUNGE"
+     */
+    imapExec(accountId: string, commands: string[]): Promise<{
+        success: boolean;
+        responses: ImapResponse[];
+    }>;
+    /**
+     * Move emails to trash (soft delete)
+     */
+    trashEmails(accountId: string, uids: number[]): Promise<{
+        success: boolean;
+        moved: number;
+    }>;
+    /**
+     * Archive emails (remove from inbox, keep in All Mail)
+     */
+    archiveEmails(accountId: string, uids: number[]): Promise<{
+        success: boolean;
+        archived: number;
+    }>;
+    /**
+     * List available folders
+     */
+    listFolders(accountId: string): Promise<{
+        success: boolean;
+        folders: FolderInfo[];
+    }>;
+}

package/dist/components/AnimatedCardFlip.d.ts

@@ -0,0 +1,19 @@
+export interface AnimatedCardFlipNode {
+    _id: string;
+    type: string;
+    title: string;
+    data: {
+        name: string;
+        image: string;
+    };
+}
+export interface AnimatedCardFlipProps {
+    nodes: AnimatedCardFlipNode[];
+    cardCount?: number;
+    minInterval?: number;
+    maxInterval?: number;
+    onCardClick?: (node: AnimatedCardFlipNode) => void;
+    cardSize?: 'small' | 'medium' | 'large';
+    className?: string;
+}
+export declare function AnimatedCardFlip({ nodes, cardCount, minInterval, maxInterval, onCardClick, cardSize, className }: AnimatedCardFlipProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Card.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Default Card Component for Stack list items
+ * Generic design that works with any data type
+ */
+export interface CardProps<T = any> {
+    item: T;
+    onClick?: () => void;
+    title?: (item: T) => string;
+    subtitle?: (item: T) => string;
+    image?: (item: T) => string | undefined;
+    badge?: (item: T) => string | undefined;
+}
+export declare function Card<T = any>({ item, onClick, title, subtitle, image, badge, }: CardProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/components/Detail.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Default Detail View Component
+ * Generic detail view for any item
+ */
+export interface DetailProps<T = any> {
+    item: T | null;
+    onClose?: () => void;
+    title?: (item: T) => string;
+    image?: (item: T) => string | undefined;
+    fields?: Array<{
+        label: string;
+        value: (item: T) => any;
+    }>;
+}
+export declare function Detail<T = any>({ item, onClose, title, image, fields, }: DetailProps<T>): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/Mail.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Mail Component
+ * Smart email list with selection, actions, and detail view
+ */
+import React from 'react';
+export interface EmailMessage {
+    uid: number;
+    subject: string;
+    from: string;
+    date: string;
+    seen: boolean;
+}
+export interface MailProps {
+    baseUrl: string;
+    systemId: string;
+    accountId: string;
+    limit?: number;
+    selectable?: boolean;
+    showDetail?: boolean;
+    emptyMessage?: string;
+    autoLoad?: boolean;
+    onSelect?: (email: EmailMessage) => void;
+    onSelectionChange?: (uids: number[]) => void;
+    onDelete?: (uids: number[]) => void;
+    onError?: (error: Error) => void;
+    renderItem?: (email: EmailMessage, selected: boolean) => React.ReactNode;
+    renderDetail?: (email: EmailMessage) => React.ReactNode;
+    renderActions?: (selectedUids: number[], actions: MailActions) => React.ReactNode;
+    renderEmpty?: () => React.ReactNode;
+    renderLoading?: () => React.ReactNode;
+    theme?: MailTheme;
+}
+export interface MailTheme {
+    background?: string;
+    cardBackground?: string;
+    selectedBackground?: string;
+    unreadBackground?: string;
+    text?: string;
+    textSecondary?: string;
+    border?: string;
+    primary?: string;
+    danger?: string;
+}
+export interface MailActions {
+    delete: () => Promise<void>;
+    archive: () => Promise<void>;
+    refresh: () => Promise<void>;
+    selectAll: () => void;
+    clearSelection: () => void;
+}
+export declare function Mail({ baseUrl, systemId, accountId, limit, selectable, showDetail, emptyMessage, autoLoad, onSelect, onSelectionChange, onDelete, onError, renderItem, renderDetail, renderActions, renderEmpty, renderLoading, theme: themeProp, }: MailProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Stack.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Stack Component
+ * Apple/Superhuman inspired clean design
+ */
+import React from 'react';
+import type { QueryParams } from '../types';
+export interface StackProps<T = any> {
+    endpoint: string;
+    params?: QueryParams;
+    layout?: 'list' | 'grid' | 'masonry';
+    title?: string;
+    emptyMessage?: string;
+    renderItem?: (item: T, index: number) => React.ReactNode;
+    keyExtractor?: (item: T, index: number) => string;
+    searchable?: boolean;
+    searchFields?: (keyof T)[];
+    searchPlaceholder?: string;
+    filters?: Array<{
+        field: keyof T;
+        label: string;
+        options?: Array<{
+            value: any;
+            label: string;
+        }>;
+    }>;
+    pageSize?: number;
+    onItemClick?: (item: T) => void;
+    onRefresh?: () => void;
+    theme?: {
+        background?: string;
+        cardBackground?: string;
+        text?: string;
+        textSecondary?: string;
+        border?: string;
+        primary?: string;
+    };
+}
+export declare function Stack<T = any>({ endpoint, params, layout, title, emptyMessage, renderItem, keyExtractor, searchable, searchFields, searchPlaceholder, filters, pageSize, onItemClick, onRefresh, theme, }: StackProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/hooks/useMutation.d.ts

@@ -0,0 +1,16 @@
+import type { HttpMethod } from '../types';
+export interface UseMutationOptions<TData, TVariables> {
+    onSuccess?: (data: TData, variables: TVariables) => void;
+    onError?: (error: Error, variables: TVariables) => void;
+}
+export interface UseMutationResult<TData, TVariables> {
+    data: TData | null;
+    loading: boolean;
+    error: Error | null;
+    mutate: (variables: TVariables) => Promise<TData | null>;
+    reset: () => void;
+}
+/**
+ * Generic hook for mutations (POST, PUT, PATCH, DELETE)
+ */
+export declare function useMutation<TData = any, TVariables = any>(endpoint: string, method?: HttpMethod, options?: UseMutationOptions<TData, TVariables>): UseMutationResult<TData, TVariables>;

package/dist/hooks/useQuery.d.ts

@@ -0,0 +1,18 @@
+import type { QueryParams } from '../types';
+export interface UseQueryOptions<T> {
+    enabled?: boolean;
+    refetchOnMount?: boolean;
+    onSuccess?: (data: T) => void;
+    onError?: (error: Error) => void;
+}
+export interface UseQueryResult<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Generic hook for fetching data
+ * Similar to React Query but simpler
+ */
+export declare function useQuery<T = any>(endpoint: string, params?: QueryParams, options?: UseQueryOptions<T>): UseQueryResult<T>;

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @qwanyx/stack
+ *
+ * All-in-one data management system for React applications
+ * Combines Graph API + REST API + UI components
+ *
+ * Like HyperCard, but with React instead of HyperTalk
+ */
+export { GraphClient } from './client/GraphClient';
+export { MailClient } from './client/MailClient';
+export { ApiClient, initializeApiClient, getApiClient } from './api/client';
+export { AuthManager } from './auth';
+export { useQuery } from './hooks/useQuery';
+export type { UseQueryOptions, UseQueryResult } from './hooks/useQuery';
+export { useMutation } from './hooks/useMutation';
+export type { UseMutationOptions, UseMutationResult } from './hooks/useMutation';
+export type { GraphNode, GraphEdge, GraphClientConfig, StackItem, StackConfig, StackContainerProps, StackContext, ViewContext, CardRenderer, ViewRenderer, Editor, EditorProps, StackTheme, LayoutMode, ApiConfig, ApiResponse, PaginationParams, SortParams, FilterParams, QueryParams, PaginatedResponse, HttpMethod, RequestOptions, MailClientConfig, MailServer, MailAccount, EmailMessage, MailListResult, ImapResponse, FolderInfo, APIResponse, } from './types';
+export { Stack } from './components/Stack';
+export type { StackProps } from './components/Stack';
+export { Card } from './components/Card';
+export type { CardProps } from './components/Card';
+export { Detail } from './components/Detail';
+export type { DetailProps } from './components/Detail';
+export { AnimatedCardFlip } from './components/AnimatedCardFlip';
+export type { AnimatedCardFlipProps, AnimatedCardFlipNode } from './components/AnimatedCardFlip';
+export { Mail } from './components/Mail';
+export type { MailProps, MailTheme, MailActions } from './components/Mail';
+export { DataOperations } from './operations';

package/dist/operations/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Operations Layer
+ * Client-side data manipulation utilities
+ */
+export declare class DataOperations {
+    /**
+     * Filter array by predicate function
+     */
+    static filter<T>(items: T[], predicate: (item: T) => boolean): T[];
+    /**
+     * Filter by field value
+     */
+    static filterBy<T>(items: T[], field: keyof T, value: any): T[];
+    /**
+     * Filter by multiple fields
+     */
+    static filterByFields<T>(items: T[], filters: Partial<T>): T[];
+    /**
+     * Sort array by field
+     */
+    static sort<T>(items: T[], field: keyof T, order?: 'asc' | 'desc'): T[];
+    /**
+     * Search items by query string in specified fields
+     */
+    static search<T>(items: T[], query: string, fields: (keyof T)[]): T[];
+    /**
+     * Paginate array
+     */
+    static paginate<T>(items: T[], page: number, limit: number): {
+        data: T[];
+        total: number;
+        page: number;
+        totalPages: number;
+    };
+    /**
+     * Group items by field value
+     */
+    static groupBy<T>(items: T[], field: keyof T): Record<string, T[]>;
+    /**
+     * Get unique values for a field
+     */
+    static unique<T>(items: T[], field: keyof T): any[];
+    /**
+     * Count items by field value
+     */
+    static countBy<T>(items: T[], field: keyof T): Record<string, number>;
+    /**
+     * Apply multiple operations in sequence
+     */
+    static pipe<T>(items: T[], operations: Array<(items: T[]) => T[]>): T[];
+}

package/dist/types/index.d.ts

@@ -0,0 +1,225 @@
+/**
+ * TypeScript type definitions for Qwanyx Stack
+ */
+import { ReactNode } from 'react';
+export interface GraphNode {
+    _id: string;
+    p?: string | null;
+    type: string;
+    title?: string;
+    description?: string;
+    icon?: string;
+    editor?: string;
+    hidden?: boolean;
+    archive?: boolean;
+    data?: Record<string, any>;
+    created?: string;
+    modified?: string;
+    creator?: string;
+    owner?: string;
+    owner_group?: string | null;
+    permissions?: number;
+    acl?: string;
+}
+export interface GraphEdge {
+    source_id: string | null;
+    target_id: string;
+    edge_type: string;
+    data?: Record<string, any>;
+    created: number;
+    modified?: number;
+}
+export type StackItem = GraphNode;
+export interface StackContext {
+    apiUrl?: string;
+    systemId?: string;
+    onNavigate?: (item: StackItem) => void;
+}
+export interface ViewContext {
+    onBack?: () => void;
+    onEdit?: () => void;
+    onDelete?: () => void;
+    onOpenChat?: (nodeId: string) => void;
+    apiUrl?: string;
+    userId?: string;
+    graphClient?: any;
+}
+export type CardRenderer = (item: StackItem, context?: StackContext) => ReactNode;
+export type ViewRenderer = (item: StackItem, context?: ViewContext) => ReactNode;
+export interface EditorProps {
+    item?: StackItem;
+    graphClient: any;
+    onSave: (item: StackItem) => void;
+    onCancel: () => void;
+    onDelete?: () => void;
+    apiUrl?: string;
+    systemId?: string;
+}
+export type Editor = React.ComponentType<EditorProps>;
+export interface StackConfig {
+    id: string;
+    name?: string;
+    system_id: string;
+    parentId?: string;
+    displayMode?: 'children' | 'edges' | 'both';
+    maxWidth?: string;
+    minWidth?: string;
+    cardRenderer?: CardRenderer;
+    viewRenderer?: ViewRenderer;
+    items?: StackItem[];
+    loadItems?: () => Promise<StackItem[]>;
+    metadata?: {
+        hidden?: boolean;
+        archive?: boolean;
+        originalNode?: any;
+        isSelected?: boolean;
+    };
+    onNavigate?: (item: StackItem) => void;
+    onAdd?: () => void;
+    onAddRequest?: (data: any) => Promise<void>;
+    systemMessage?: {
+        type: 'error' | 'warning' | 'info' | 'success';
+        message: string;
+        details?: string;
+    };
+}
+export interface StackProps {
+    config: StackConfig;
+    onItemClick?: (item: StackItem) => void;
+    onClose?: () => void;
+    onClick?: (event: React.MouseEvent) => void;
+    style?: React.CSSProperties;
+    currentView?: StackItem | null;
+    viewNode?: any;
+    onCloseView?: () => void;
+    onAdd?: () => void;
+    theme?: StackTheme;
+    apiUrl?: string;
+    userId?: string;
+    onCreateColumn?: (item: StackItem, direction: 'left' | 'right') => void;
+}
+export interface StackTheme {
+    primary?: string;
+    surface?: string;
+    surfaceHover?: string;
+    muted?: string;
+    text?: string;
+    textMuted?: string;
+    success?: string;
+    error?: string;
+}
+export interface StackContainerProps {
+    stacks: StackConfig[];
+    defaultViewMode?: 'side' | 'fullscreen' | 'modal';
+    maxStacks?: number;
+    stackSpacing?: string;
+    containerPadding?: string;
+    onStackClose?: (stackId: string) => void;
+    onStackOpen?: (config: StackConfig) => void;
+    style?: React.CSSProperties;
+}
+export type LayoutMode = 'list' | 'grid' | 'masonry';
+export interface GraphClientConfig {
+    baseUrl: string;
+    system_id: string;
+}
+export interface APIResponse<T = any> {
+    success: boolean;
+    data?: T;
+    result?: T;
+    error?: string;
+}
+export interface ApiConfig {
+    baseUrl: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+export interface ApiResponse<T = any> {
+    data: T;
+    success: boolean;
+    message?: string;
+    error?: string;
+}
+export interface PaginationParams {
+    page?: number;
+    limit?: number;
+    offset?: number;
+}
+export interface SortParams {
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+}
+export interface FilterParams {
+    [key: string]: any;
+}
+export interface QueryParams extends PaginationParams, SortParams, FilterParams {
+}
+export interface PaginatedResponse<T = any> {
+    data: T[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface RequestOptions {
+    method?: HttpMethod;
+    headers?: Record<string, string>;
+    body?: any;
+    params?: QueryParams;
+}
+export interface MailClientConfig {
+    baseUrl: string;
+    system_id: string;
+}
+export interface MailServer {
+    host: string;
+    port: string;
+    user: string;
+    password: string;
+}
+export interface MailAccount {
+    id: string;
+    label: string;
+    firstName: string;
+    lastName: string;
+    email: string;
+    signature?: string;
+    imap: MailServer;
+    smtp: MailServer;
+}
+export interface EmailMessage {
+    uid: number;
+    subject: string;
+    from: string;
+    date: string;
+    seen: boolean;
+}
+export interface MailListResult {
+    account: {
+        id: string;
+        label: string;
+        email: string;
+    };
+    mailbox: {
+        name: string;
+        total: number;
+    };
+    messages: EmailMessage[];
+}
+export interface ImapResponse {
+    ok: boolean;
+    command: string;
+    error?: string;
+    mailbox?: string;
+    exists?: number;
+    recent?: number;
+    unseen?: number;
+    folders?: FolderInfo[];
+    uid?: string;
+}
+export interface FolderInfo {
+    name: string;
+    delimiter: string | null;
+    attributes: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwanyx/stack",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Modern HyperCard for React - All-in-one data management (REST + Graph API + Auth + Hooks + UI)",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",