@sprinterai/core

pnpm add @sprinterai/core

import { defineEntityType, field } from "@sprinterai/core";

const opportunity = defineEntityType({
  slug: "opportunity",
  name: "Opportunity",
  description: "A deal in the pipeline",
  icon: "target",
  color: "#3B82F6",
  schema: {
    type: "object",
    properties: {
      name: field.text({ title: "Deal Name" }),
      stage: field.select({
        title: "Stage",
        options: ["Sourced", "Screening", "Due Diligence", "Closed"],
      }),
      value: field.currency({ title: "Deal Value" }),
      probability: field.percentage({ title: "Close Probability" }),
      target_close: field.date({ title: "Target Close Date" }),
      website: field.url({ title: "Company Website" }),
      tags: field.array({ title: "Tags", itemType: "string" }),
    },
    required: ["name", "stage"],
  },
  config: {
    ui: { defaultLayout: "kanban" },
  },
});

import { defineAgent } from "@sprinterai/core";

const researcher = defineAgent({
  slug: "researcher",
  name: "Research Agent",
  description: "Researches entities using web search and analysis",
  systemPrompt: "You are a thorough research analyst...",
  model: "claude-sonnet-4-20250514",
  toolGroups: ["entity", "web"],
  customTools: ["roi-calculator"],
});

import { defineTool } from "@sprinterai/core";
import { z } from "zod";

const scorer = defineTool({
  slug: "deal-scorer",
  name: "Deal Scorer",
  description: "Score a deal on multiple dimensions",
  category: "analysis",
  requiredPermission: "entities.team.update",
  inputSchema: z.object({
    entityId: z.string(),
    dimensions: z.array(z.string()),
  }),
  execute: async (input) => {
    // scoring logic
    return { scores: {} };
  },
});

import { defineWorkflow } from "@sprinterai/core";

const enrichment = defineWorkflow([
  { id: "fetch-basics", agentSlug: "researcher", fieldKey: "name" },
  { id: "fetch-financials", agentSlug: "analyst", fieldKey: "revenue", dependsOn: ["fetch-basics"] },
  { id: "score", agentSlug: "scorer", fieldKey: "score", dependsOn: ["fetch-financials"], outputType: "field" },
]);

import { defineModule, defineApp } from "@sprinterai/core";

const dealFlow = defineModule({
  name: "deal-flow",
  description: "Deal pipeline and scoring",
  entityTypes: [opportunity],
  agents: [researcher],
  tools: [scorer],
  dependencies: ["core-entities"],
});

const app = defineApp({
  name: "portfolio-intel",
  description: "PE portfolio intelligence",
  modules: [dealFlow],
});

import {
  SURFACE_TYPES,
  SURFACE_TYPE_META,
  SurfaceTypeSchema,
  getSurfaceTypeMeta,
  surfaceTypesByCategory,
} from "@sprinterai/core";

// Validate a string against the known set
const result = SurfaceTypeSchema.safeParse(userInput);

// Metadata lookup with safe fallback
const meta = getSurfaceTypeMeta("kanban");
// { label: "Kanban", category: "data", interactive: true, fullscreen: false, ... }

// All types grouped by category
const grouped = surfaceTypesByCategory();
// { core: ["grid", "sequence", ...], data: ["split", "kanban", ...], ... }

import {
  SurfaceDefinitionRegistry,
  defineSurface,
  surfaceDefinitions,
} from "@sprinterai/core";
import { z } from "zod";

// Define a surface with a typed config schema
const kanbanDef = defineSurface({
  type: "kanban",
  meta: { label: "Kanban", description: "...", category: "data", icon: "Columns3" },
  capabilities: {
    interactive: true,
    fullscreen: false,
    supportsPublishing: false,
    requiresClientSide: true,
  },
  configSchema: z.object({ groupByField: z.string() }),
});

// Register in the singleton
surfaceDefinitions.register(kanbanDef);

// Introspect at runtime
const info = surfaceDefinitions.introspect("kanban");
// { type, category, label, description, interactive, fullscreen, supportsPublishing }

// All registered definitions
const all = surfaceDefinitions.introspectAll();

import {
  AggregationParamsSchema,
  AggregationFunctionSchema,
  AggregationOperatorSchema,
} from "@sprinterai/core";
import type {
  AggregationParams,
  AggregationFunction,
  AggregationFilter,
  AggregationResult,
} from "@sprinterai/core";

// Validate aggregation query parameters
const params = AggregationParamsSchema.parse({
  entityTypeSlug: "opportunity",
  groupBy: "stage",
  aggregations: [
    { field: "value", function: "sum", alias: "total_value" },
    { field: "id",    function: "count", alias: "deal_count" },
  ],
  filters: [
    { field: "status", operator: "eq", value: "active" },
  ],
});

interface AggregationResultRow {
  group?: string | null;          // Present when groupBy was requested
  [alias: string]: number | string | null | undefined;
}

interface AggregationResult {
  results: AggregationResultRow[];
  total: number;
}

import { RelationColumnSchema, FilterRuleSchema } from "@sprinterai/core";
import type { RelationColumn, FilterRule, RelationColumnResult } from "@sprinterai/core";

const activityCount: RelationColumn = {
  label: "Activity Count",
  relatedTypeSlug: "activity",
  relationshipType: "has_activity",
  aggregation: "count",
};

const lastCallDate: RelationColumn = {
  label: "Last Call",
  relatedTypeSlug: "activity",
  relationshipType: "has_activity",
  aggregation: "latest",
  field: "date",
  filters: [{ field: "activity_type", operator: "eq", value: "call" }],
};

import { ANALYTICS_EVENTS } from "@sprinterai/core";
import type { AnalyticsEvent, AnalyticsProvider, AnalyticsEventType } from "@sprinterai/core";

interface AnalyticsProvider {
  track(event: AnalyticsEvent): void | Promise<void>;
}

import { canAccessView, canModifyView } from "@sprinterai/core/view";
import type { ViewAccessContext } from "@sprinterai/core/view";

interface ViewAccessContext {
  tenantId: string;
  userId: string;
  /** Role-based permission strings — e.g. 'views.team.update', 'admin'. */
  permissions: string[];
}

import { AUDIT_ACTIONS } from "@sprinterai/core";
import type { AuditAction, AuditStore, AuditLogFilters } from "@sprinterai/core";

INSERT  UPDATE  DELETE  LOGIN  LOGOUT
PERMISSION_CHANGE  EXPORT  IMPORT  BULK_OPERATION

interface AuditStore {
  listAuditLogs(tenantId: string, filters?: AuditLogFilters): Promise<ListAuditLogsResult>;
  getAuditLog(tenantId: string, id: string): Promise<AuditLogRecord | null>;
  createAuditLog(tenantId: string, entry: Omit<AuditLogRecord, 'id' | 'tenant_id' | 'created_at'>): Promise<AuditLogRecord>;
  batchCreateAuditLogs(
    tenantId: string,
    entries: Array<Omit<AuditLogRecord, 'id' | 'tenant_id' | 'created_at'>>,
    correlationId?: string,
  ): Promise<AuditLogRecord[]>;
}

import {
  FALLBACK_MODEL_CATALOG,
  PROVIDER_ORDER,
  PROVIDER_LABELS,
  PROVIDER_DEFAULT_MODEL,
  DEFAULT_CHAT_MODEL_ID,
  DEFAULT_IMAGE_MODEL_ID,
  groupModelsByProvider,
} from "@sprinterai/core";
import type {
  ModelCapability,
  ModelCatalogEntry,
  ModelInfo,
  ModelProvider,
} from "@sprinterai/core";

interface ModelCatalogEntry {
  id: string;                   // Canonical ID, e.g. 'claude-sonnet-4-6'
  provider: ModelProvider;      // 'anthropic' | 'openai' | 'google' | 'xai' | 'deepseek'
  name: string;
  description?: string | null;
  capabilities: ModelCapability[];
  speedTier: 'fast' | 'medium' | 'slow';
  reasoningLevel?: 'low' | 'medium' | 'high' | null; // Only for 'reasoning' models
  costPer1mInput: number;       // USD per 1 million input tokens
  costPer1mOutput: number;      // USD per 1 million output tokens
  enabled?: boolean;
}

interface ModelInfo {
  id?: string;
  model_id: string;
  display_name: string;
  provider: ModelProvider;
  speed_tier: 'fast' | 'medium' | 'slow';
  capabilities?: ModelCapability[];
  description?: string | null;
  reasoning_level?: 'low' | 'medium' | 'high' | null;
  cost_per_1m_input?: number;
  cost_per_1m_output?: number;
  enabled?: boolean;
  sort_order?: number;
}

const { grouped, sortedProviders } = groupModelsByProvider(FALLBACK_MODEL_CATALOG);
// grouped: Map<ModelProvider, ModelCatalogEntry[]>
// sortedProviders: ['anthropic', 'openai', 'google', 'xai', 'deepseek'] (only those present)

import {
  BLOCK_TYPES,
  BlockConfigSchema,
  DataSourceConfigSchema,
  VIEW_LAYOUTS,
  VIEW_THEMES,
  BLOCK_SIZES,
} from "@sprinterai/core";
import type {
  BlockType,
  BlockConfig,
  DataSourceConfig,
  BlockWorkflow,
  ViewLayoutStyle,
  ViewTheme,
  BlockSize,
  BlockRole,
  FormFlowConfig,
} from "@sprinterai/core";

stat-cards, table, chart, radar, ranking, kanban, summary,
field-card, connection-list, data-table, activity, entity-card,
entity-feed, rich-text, status-banner, child-entity-list, custom,
image, video, excalidraw, react-flow, bubble-chart, entity-graph,
form-flow, canvas, menu, pdf-viewer, response-form, entity-filter,
notes, documents, tool, resource-download

const block: BlockConfig = {
  id: "blk-abc123",
  type: "chart",
  label: "Revenue by Stage",
  size: "half",          // legacy: 'full' | 'half' | 'third'
  span: 6,               // preferred: 12-column grid span (1-12)
  row: 2,                // optional explicit row placement (1-based)
  height: 3,             // grid row units
  dataSourceId: "opportunities",
  clickAction: { type: "navigate", target: "/entities/:id" },
};

const ds: DataSourceConfig = {
  entityTypeSlug: "opportunity",
  filters: [{ field: "status", operator: "eq", value: "active" }],
  sort: { field: "updated_at", order: "desc" },
  limit: 50,
  relationColumns: {
    activity_count: {
      label: "Activities",
      relatedTypeSlug: "activity",
      relationshipType: "has_activity",
      aggregation: "count",
    },
  },
};

interface FormFlowConfig {
  steps: FormFlowStep[];
  completionMessage?: string;
  allowSkipOptional?: boolean;
  output?: FormFlowOutputConfig;
}

interface FormFlowStep {
  id: string;
  title: string;
  description?: string;
  fields: FormFlowField[];
  instructions?: string;
}

const FileUploadFieldConfigSchema = z.object({
  accept: z.array(z.string()).optional(),  // MIME types or extensions e.g. ['image/*', '.pdf']
  maxBytes: z.number().optional(),         // Maximum file size per file
  multiple: z.boolean().optional(),        // Allow multiple files
});

const ResourceDownloadBlockConfigSchema = z.object({
  title: z.string().optional(),
  message: z.string().optional(),
  downloadUrl: z.string().optional(),
  downloadLabel: z.string().optional(),
});

type FormFlowOutputConfig =
  | { type: 'entity'; entityTypeSlug: string }   // Create an entity from collected fields
  | { type: 'webhook'; webhookUrl: string }       // POST collected data to an endpoint
  | { type: 'none' };                             // No action — show completion message only

import {
  BLOCK_DATA_SCHEMAS,
  getBlockDataSchema,
  ActivityBlockDataSchema,
  EntityCardBlockDataSchema,
  RadarBlockDataSchema,
} from "@sprinterai/core";
import type {
  ActivityBlockData,
  EntityCardBlockData,
  RadarBlockData,
} from "@sprinterai/core";

// Look up by block type string
const schema = getBlockDataSchema("activity");
// Returns ActivityBlockDataSchema, or undefined for unknown types

// Validate before rendering
const result = schema?.safeParse(rawData);

// All schemas in a keyed map
const allSchemas = BLOCK_DATA_SCHEMAS;
// Record<string, z.ZodType>

import { parseViewBlocks, orderedBlocks, blockCount } from "@sprinterai/core";
import type { ParsedViewRecord, ViewPageKind, ViewInventoryRecord } from "@sprinterai/core";

interface ParsedViewRecord {
  id: string;
  tenant_id: string;
  entity_type_id: string | null;
  entity_type_slug: string | null;
  entity_id: string | null;
  title: string;
  slug: string;
  page_type: ViewPageKind;        // 'list' | 'workspace'
  blocks: Record<string, BlockConfig>;
  blockOrder: string[];
  layout: ViewLayoutStyle;        // 'stack' | 'grid-2' | 'grid-3' | 'bento' | 'single'
  scope: 'default' | 'shared' | 'user';
  dataSources: Record<string, DataSourceConfig>;
  theme: ViewTheme;               // 'dashboard' | 'page' | 'minimal' | 'embed'
  surface_type: string;
  surface_config: Record<string, unknown>;
  is_default: boolean | null;
  parent_view_id: string | null;
  created_at: string;
  updated_at: string;
}

const { blocks, blockOrder } = parseViewBlocks(rawBlocks, rawBlockOrder);

// Ordered array of BlockConfig for rendering loops
const rendered = orderedBlocks(view);

// Block count (length of blockOrder)
const count = blockCount(view);

import {
  PluginManifestSchema,
  CreatePluginInputSchema,
  UpdatePluginInputSchema,
  CreateVersionInputSchema,
  CreateBindingInputSchema,
  PLUGIN_STATUSES,
  VERSION_STATUSES,
  RENDERER_SOURCES,
  SANDBOX_ACTIONS,
} from "@sprinterai/core";
import type {
  PluginManifest,
  PluginRecord,
  PluginVersionRecord,
  RendererBindingRecord,
} from "@sprinterai/core";

const manifest: PluginManifest = {
  name: "custom-chart",
  version: "1.2.0",
  family: "block",
  description: "Custom D3 chart renderer",
  targets: ["record:chart", "record:chart:opportunity"],
  dataBindings: { record: true, schema: true, viewConfig: true },
  actions: ["update-field", "navigate"],
  configSchema: { colorScheme: { type: "string" } },
};

import type {
  PdfDocumentProxy,
  PdfHighlight,
  SelectionContext,
  SelectionAction,
  PdfWorkerConfig,
  PdfLoadOptions,
} from "@sprinterai/core";

type PdfDocumentProxy = {
  numPages: number;
  getPage: (pageNum: number) => Promise<unknown>;
  getDestination: (dest: string) => Promise<unknown>;
  getPageIndex: (pageRef: unknown) => Promise<number>;
  destroy: () => void;
};

interface PdfHighlight {
  id: string;
  page: number;    // 0-based page index
  x: number;      // normalized 0-1 within page
  y: number;
  width: number;
  height: number;
  color?: string;  // CSS color string
  text?: string;   // captured text content of the highlighted region
}

interface SelectionContext {
  text: string;
  pageIndex: number;
  coordinates: { x: number; y: number; width: number; height: number };
  rect: { top: number; left: number; bottom: number; right: number; width: number; height: number };
}

interface SelectionAction {
  id: string;
  label: string;
  icon?: string;   // Lucide icon name
  onAction: (context: SelectionContext) => void;
}

import type {
  EmailChannel,
  EmailMessage,
  EmailProvider,
  SendEmailInput,
  SendEmailResult,
  NotificationEmailContext,
  DigestEmailContext,
  NotificationPreferences,
} from "@sprinterai/core/email";

import {
  SendEmailInputSchema,
  NotificationPreferencesSchema,
  DEFAULT_NOTIFICATION_PREFERENCES,
} from "@sprinterai/core/email";

const prefs = NotificationPreferencesSchema.parse(rawUserSettings);
// {
//   emailFrequency: "realtime" | "daily" | "weekly" | "never"  (default: "never")
//   emailNotifications: boolean                                 (default: false)
//   inAppNotifications: boolean                                 (default: true)
//   activityUpdates: boolean                                    (default: true)
// }

import type { EmailConfig, ProviderConfig } from "@sprinterai/core";

interface EntityStore {
  getEntityType(slugOrId: string): Promise<EntityTypeRecord | null>;
  listEntityTypes(): Promise<EntityTypeRecord[]>;
  getEntity(id: string): Promise<EntityRecord | null>;
  searchEntities(query: string, options?: { typeSlug?: string; tag?: string; limit?: number }): Promise<EntityRecord[]>;
  createEntity(input: CreateEntityInput): Promise<EntityRecord>;
  updateEntity(id: string, input: UpdateEntityInput): Promise<EntityRecord>;
  deleteEntity(id: string): Promise<void>;
  createRelation(fromId: string, toId: string, type: string): Promise<void>;
  getEntityCounts(tenantId: string): Promise<Record<string, number>>;
}

interface ChatStore {
  // Core message operations
  getChat(chatId: string): Promise<ConversationListItem | null>;
  createChat(options: { title?: string; chatType: 'ai' | 'direct' | 'group'; agentSlug?: string; userId?: string }): Promise<ConversationListItem>;
  getMessages(chatId: string, options?: { limit?: number; before?: string }): Promise<MessageRecord[]>;
  saveMessage(chatId: string, input: SaveMessageInput): Promise<MessageRecord>;
  getChatsByUser(userId: string, options?: { limit?: number }): Promise<ConversationListItem[]>;

  // Participant management
  getParticipants(chatId: string): Promise<ChatParticipant[]>;
  addParticipant(chatId: string, tenantId: string, participantId: string, participantType: ParticipantType, options?: { role?: ParticipantRole; autoRespond?: boolean }): Promise<ChatParticipant>;
  removeParticipant(chatId: string, participantId: string): Promise<void>;

  // Unread tracking
  markAsRead(chatId: string, userId: string): Promise<void>;
  getUnreadCount(userId: string): Promise<number>;
}

interface ChatParticipant {
  id: string;
  chat_id: string;
  tenant_id: string;
  participant_type: ParticipantType; // 'user' | 'agent'
  participant_id: string;
  role: ParticipantRole;             // 'owner' | 'member'
  auto_respond: boolean;
  joined_at: string;
  last_read_at: string;
}

import type {
  ChatParticipant,
  ParticipantType,
  ParticipantRole,
  ConversationListItem,
  ChatStore,
} from "@sprinterai/core";

import { ROLE_IDS, isAdminRole, mapRoleSlug } from "@sprinterai/core";

// ROLE_IDS maps slug -> UUID
const adminRoleId = ROLE_IDS.tenant_admin;

// Check if a role is admin-level
isAdminRole("system_admin"); // true
isAdminRole("viewer");       // false

// Map DB role slug to app role
mapRoleSlug("system_admin"); // "owner"

import { computeResponseScore, isNumericDimension } from "@sprinterai/core";

// Compute weighted score from dimension scores
const score = computeResponseScore(dimensionScores, criteriaSet);

import type {
  AutomationType,
  UnifiedAutomation,
  AutomationRun,
  AutomationStore,
} from "@sprinterai/core";
import { AUTOMATION_TYPES, AUTOMATION_TYPE_LABELS, AUTOMATION_TYPE_ICONS } from "@sprinterai/core";

type AutomationType = 'heartbeat' | 'source-sync';

interface UnifiedAutomation {
  id: string;
  name: string;
  type: AutomationType;
  icon: string;
  schedule: string | null;       // cron expression, or null if not scheduled
  scheduleHuman: string;         // human-readable schedule description
  enabled: boolean;
  lastRunAt: string | null;
  lastRunStatus: string | null;
  nextRunAt: string | null;
  agentId?: string;              // heartbeat automations only
  entityId?: string;             // source-sync automations only
}

interface AutomationRun {
  id: string;
  status: string;
  started_at: string | null;
  completed_at: string | null;
  duration_ms: number | null;
  tokens_used: number | null;
  cost_cents: number | null;
  error_log: string | null;
  metadata: Record<string, unknown> | null;
  chat_id: string | null;        // linked chat session, if any
}

interface AutomationStore {
  listAutomations(tenantId: string): Promise<UnifiedAutomation[]>;
  getAutomation(tenantId: string, id: string): Promise<UnifiedAutomation | null>;
  setEnabled(tenantId: string, id: string, enabled: boolean): Promise<void>;
  listRuns(tenantId: string, automationId: string, limit?: number): Promise<AutomationRun[]>;
}

import type { TenantSetting, SettingKey, JobFunction, DashboardPreferences, SettingsStore } from "@sprinterai/core";
import { SETTING_KEYS, JOB_FUNCTIONS, JOB_FUNCTION_LABELS } from "@sprinterai/core";

interface TenantSetting {
  id: string;
  tenantId: string;
  userId: string | null;    // null = tenant-level; string = user-scoped
  key: SettingKey;
  value: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
}

interface DashboardPreferences {
  jobFunction?: JobFunction;          // 'executive' | 'sales' | 'content_ops' | 'operations' | 'analyst' | 'other'
  pinnedEntityTypes?: string[];
  onboardingCompleted?: boolean;
}

interface SettingsStore {
  getSetting(tenantId: string, key: SettingKey, userId?: string): Promise<TenantSetting | null>;
  setSetting(tenantId: string, key: SettingKey, value: Record<string, unknown>, userId?: string): Promise<TenantSetting>;
  listSettings(tenantId: string, userId?: string): Promise<TenantSetting[]>;
  deleteSetting(tenantId: string, key: SettingKey, userId?: string): Promise<void>;
}

import { BrandingConfigSchema, DEFAULT_BRANDING } from "@sprinterai/core";
import type { BrandingConfig } from "@sprinterai/core";

// Validate incoming branding payload at the API boundary
const branding = BrandingConfigSchema.parse(rawValue);

interface BrandingConfig {
  appName?: string;    // Sidebar header text (max 50 chars)
  logoUrl?: string;    // Custom logo image URL (takes precedence over logoIcon)
  logoIcon?: string;   // Icon name from the platform icon map (max 50 chars)
  tagline?: string;    // Subtitle under app name (max 100 chars)
}

const DEFAULT_BRANDING = {
  appName: 'Sprinter',
  tagline: 'AI-powered workspace',
};

import type {
  WorkspaceTemplate,
  TemplateView,
  TemplateSampleEntity,
  TemplateCategory,
  ApplyTemplateOptions,
  ApplyTemplateResult,
  TemplateStore,
} from "@sprinterai/core";
import { TEMPLATE_CATEGORIES, TEMPLATE_CATEGORY_LABELS } from "@sprinterai/core";

interface ApplyTemplateOptions {
  createSampleEntities?: boolean;   // default: false
  updateNavigation?: boolean;       // default: true
  applyTheme?: boolean;             // default: false
}

interface ApplyTemplateResult {
  entityTypesCreated: number;
  agentsCreated: number;
  navigationUpdated: boolean;
  themeUpdated: boolean;
  viewsCreated?: number;
  sampleEntitiesCreated?: number;
}

import {
  EXTERNAL_DATA_SOURCE_TYPES,
  MetricItemSchema,
  WebhookPayloadSchema,
  CreateDataSourceSchema,
  UpdateDataSourceSchema,
  PollConfigSchema,
  ApiConfigSchema,
} from "@sprinterai/core";
import type {
  ExternalDataSourceType,
  ExternalDataSource,
  ExternalDataPoint,
  DataPointMetadata,
  MetricItem,
  WebhookPayload,
  CreateDataSourceInput,
  UpdateDataSourceInput,
  PollConfig,
  ApiConfig,
  CreateDataPointInput,
  ExternalDataStore,
} from "@sprinterai/core";

interface ExternalDataSource {
  id: string;
  tenant_id: string;
  name: string;
  description: string | null;
  source_type: ExternalDataSourceType; // 'webhook' | 'api'
  token: string;                        // unique routing token in webhook URL
  signature_secret: string | null;      // HMAC-SHA256 secret; null = unsigned
  signature_header: string;             // header carrying the signature value
  enabled: boolean;
  last_received_at: string | null;
  push_count: number;
  created_at: string;
  updated_at: string;
}

interface ExternalDataPoint {
  id: string;
  data_source_id: string;
  tenant_id: string;
  metric_key: string;    // e.g. 'monthly_revenue', 'active_users'
  label: string;         // display label
  value: number;
  metadata: DataPointMetadata;
  recorded_at: string;   // ISO timestamp — may be back-dated by the sender
  created_at: string;
}

interface DataPointMetadata {
  change?: string;  // relative change string, e.g. "+3.2%" or "-120"
  icon?: string;    // Lucide icon name
  unit?: string;    // unit label, e.g. "%", "$", "users"
  group?: string;   // grouping key for chart series
  [key: string]: unknown;
}

// Validated payload shape
const payload = WebhookPayloadSchema.parse(rawBody);
// { metrics: MetricItem[] }

// MetricItem — one measurement per key
const item: MetricItem = {
  key: "monthly_revenue",
  label: "Monthly Revenue",
  value: 125000,
  change: "+12.4%",     // optional
  unit: "$",            // optional
  icon: "trending-up",  // optional
  recorded_at: "2026-04-01T00:00:00Z", // optional — defaults to now
};

// Polling source: scheduled pull
const pollConfig = PollConfigSchema.parse({
  pollUrl: "https://api.example.com/metrics",
  pollInterval: "1h",       // '5m' | '15m' | '1h' | '6h' | '24h'
  pollTransform: "data.metrics", // JSONPath to extract metrics array
  pollHeaders: { Authorization: "Bearer token" },
});

// On-demand API source
const apiConfig = ApiConfigSchema.parse({
  apiUrl: "https://api.example.com/stats",
  apiHeaders: { "X-API-Key": "..." },
  apiTransform: "results",
  cacheTtl: 300,  // seconds; default 300
});

interface ExternalDataStore {
  listDataSources(tenantId: string): Promise<ExternalDataSource[]>;
  getDataSourceByToken(token: string): Promise<ExternalDataSource | null>;
  createDataSource(tenantId: string, input: CreateDataSourceInput): Promise<ExternalDataSource>;
  updateDataSource(id: string, tenantId: string, input: UpdateDataSourceInput): Promise<ExternalDataSource | null>;
  deleteDataSource(id: string, tenantId: string): Promise<void>;
  recordDataPoints(points: CreateDataPointInput[]): Promise<ExternalDataPoint[]>;
  getLatestMetrics(dataSourceId: string): Promise<ExternalDataPoint[]>;
  getMetricHistory(dataSourceId: string, metricKey: string, limit?: number): Promise<ExternalDataPoint[]>;
}

import {
  generateEntityMarkdown,
  parseEntityMarkdown,
  extractWikilinkTitles,
} from "@sprinterai/core";
import type {
  GenerateEntityMarkdownInput,
  ParsedEntityMarkdown,
} from "@sprinterai/core";

const md = generateEntityMarkdown({
  title: "Acme Corp",
  typeSlug: "account",
  content: { stage: "active", arr: "1200000" },
  tags: ["portfolio", "saas"],
  body: "Notes about Acme Corp. See also [[Beta Inc]].",
});

// ---
// type: account
// tags: [portfolio, saas]
// stage: active
// arr: 1200000
// ---
//
// # Acme Corp
//
// Notes about Acme Corp. See also [[Beta Inc]].

const parsed = parseEntityMarkdown(markdown);
// {
//   typeSlug: "account",
//   title: "Acme Corp",
//   body: "Notes about Acme Corp. See also [[Beta Inc]].",
//   content: { stage: "active", arr: "1200000" },
//   tags: ["portfolio", "saas"],
//   wikilinkTitles: ["Beta Inc"],
// }

extractWikilinkTitles("See [[Acme Corp]] and [[Acme Corp]] and [[Beta Inc]].");
// ["Acme Corp", "Beta Inc"]

import type { ViewResponse, ViewResponseStore } from "@sprinterai/core";

interface ViewResponse {
  id: string;
  viewId: string;
  publishToken: string;
  sessionId: string;
  data: Record<string, unknown>;  // Collected form field values
  completedAt: string | null;     // ISO timestamp, or null if still in progress
  createdAt: string;
  updatedAt: string;
}

interface ViewResponseStore {
  // Create or update a response for the given session
  upsertResponse(params: UpsertViewResponseParams): Promise<ViewResponse>;

  // Look up an in-progress or completed response by session
  getBySession(params: GetViewResponseBySessionParams): Promise<ViewResponse | null>;

  // Mark a response as completed (sets completedAt to now)
  completeResponse(params: CompleteViewResponseParams): Promise<ViewResponse | null>;

  // List all responses for a view (requires tenantId for scoping)
  listByView(viewId: string, tenantId: string): Promise<ViewResponse[]>;
}