@rawdash/core 0.3.0 → 0.4.0

package/README.md

@@ -68,11 +68,11 @@ Validates and returns a `Dashboard`. Widget keys must be URL-safe (`[a-zA-Z0-9_-
 
 ### `defineMetric(options)`
 
-Returns a `ResolvedMetric` that can be used in stat, timeseries, and distribution widgets.
+Returns a `ComputedMetric` that can be used in stat, timeseries, and distribution widgets.
 
 ### `secret(name)`
 
-Returns a `SecretRef` that resolves the named environment variable at runtime. Connectors that accept a `token` or API key should use this to avoid hardcoding credentials.
+Returns a `Secret` that resolves the named environment variable at runtime. Connectors that accept a `token` or API key should use this to avoid hardcoding credentials.
 
 ### `defineConnector(options)`
 

package/dist/index.d.ts

@@ -1,20 +1,205 @@
-import { E as Event, M as Metric, D as Distribution, S as StorageHandle, C as Connector, a as ServerStorage, W as WidgetEntry, b as SyncState } from './server-storage-BGSLkDoF.js';
-export { B as BaseConnector, c as CredentialEntry, d as CredentialSchema, e as DistributionQuery, f as Edge, g as EdgeQuery, h as Entity, i as EntityQuery, j as EnvSecretsResolver, k as EventQuery, I as InferCredentialInput, l as InferCredentials, J as JSONValue, m as MetricQuery, n as SecretRef, o as SecretsResolver, p as SyncRequest, q as defineConnector, r as isSecretRef, s as resolveSecretRefs, t as secret } from './server-storage-BGSLkDoF.js';
 import { z } from 'zod';
 
+type Secret = {
+    $secret: string;
+};
+declare function secret(name: string): Secret;
+declare function isSecret(value: unknown): value is Secret;
+interface SecretsResolver {
+    resolve(name: string): string | undefined;
+}
+declare class EnvSecretsResolver implements SecretsResolver {
+    resolve(name: string): string | undefined;
+}
+declare function resolveSecrets<T>(obj: T, resolver: SecretsResolver): T;
+
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+interface Event {
+    name: string;
+    start_ts: number;
+    end_ts: number | null;
+    attributes: Record<string, JSONValue>;
+}
+interface Entity {
+    type: string;
+    id: string;
+    attributes: Record<string, JSONValue>;
+    updated_at: number;
+}
+interface MetricSample {
+    name: string;
+    ts: number;
+    value: number;
+    attributes: Record<string, JSONValue>;
+}
+interface Edge {
+    from_type: string;
+    from_id: string;
+    kind: string;
+    to_type: string;
+    to_id: string;
+    attributes: Record<string, JSONValue>;
+    updated_at: number;
+}
+type Distribution = {
+    name: string;
+    ts: number;
+    kind: 'histogram';
+    data: {
+        buckets: Array<{
+            le: number;
+            count: number;
+        }>;
+        count: number;
+        sum: number;
+    };
+    attributes: Record<string, JSONValue>;
+} | {
+    name: string;
+    ts: number;
+    kind: 'summary';
+    data: {
+        quantiles: Array<{
+            q: number;
+            value: number;
+        }>;
+        count: number;
+        sum: number;
+    };
+    attributes: Record<string, JSONValue>;
+};
+interface EventQuery {
+    name?: string;
+    start?: number;
+    end?: number;
+}
+interface EntityQuery {
+    type: string;
+}
+interface MetricQuery {
+    name?: string;
+    start?: number;
+    end?: number;
+}
+interface EdgeQuery {
+    fromType?: string;
+    fromId?: string;
+    kind?: string;
+    toType?: string;
+    toId?: string;
+}
+interface DistributionQuery {
+    name?: string;
+    start?: number;
+    end?: number;
+}
+interface StorageHandle {
+    event(e: Event): Promise<void>;
+    entity(e: Entity): Promise<void>;
+    metric(m: MetricSample): Promise<void>;
+    edge(e: Edge): Promise<void>;
+    distribution(d: Distribution): Promise<void>;
+    events(es: Event[], scope?: {
+        names?: string[];
+    }): Promise<void>;
+    entities(es: Entity[], scope?: {
+        types?: string[];
+    }): Promise<void>;
+    metrics(ms: MetricSample[], scope?: {
+        names?: string[];
+    }): Promise<void>;
+    edges(es: Edge[], scope?: {
+        kinds?: string[];
+    }): Promise<void>;
+    distributions(ds: Distribution[], scope?: {
+        names?: string[];
+    }): Promise<void>;
+    queryEvents(q: EventQuery): Promise<Event[]>;
+    getEntity(type: string, id: string): Promise<Entity | null>;
+    queryEntities(q: EntityQuery): Promise<Entity[]>;
+    queryMetrics(q: MetricQuery): Promise<MetricSample[]>;
+    traverse(q: EdgeQuery): Promise<Edge[]>;
+    queryDistributions(q: DistributionQuery): Promise<Distribution[]>;
+    deleteOlderThan(shape: 'events' | 'metrics' | 'distributions', tsUnixMs: number): Promise<{
+        rowsDeleted: number;
+    }>;
+}
+interface CredentialField {
+    description: string;
+    auth?: 'none' | 'optional' | 'required';
+}
+type CredentialsSchema = Record<string, CredentialField>;
+type InferCredentials<TCreds extends CredentialsSchema> = {
+    [K in keyof TCreds]: TCreds[K] extends {
+        auth: 'required';
+    } ? string : string | undefined;
+};
+type InferCredentialInput<TCreds extends CredentialsSchema> = {
+    [K in keyof TCreds]: TCreds[K] extends {
+        auth: 'required';
+    } ? string | Secret : string | Secret | undefined;
+};
+interface SyncOptions {
+    mode: 'full' | 'latest';
+    since?: string;
+}
+interface Connector {
+    readonly id: string;
+    readonly credentials?: CredentialsSchema;
+    serializeConfig(): Record<string, unknown>;
+    sync(options: SyncOptions, storage: StorageHandle, signal?: AbortSignal): Promise<void>;
+}
+interface RetryPolicy {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    signal?: AbortSignal;
+}
+declare abstract class BaseConnector<TSettings = unknown, TCreds extends CredentialsSchema = CredentialsSchema> implements Connector {
+    abstract readonly id: string;
+    readonly credentials?: TCreds;
+    protected settings: TSettings;
+    protected creds: InferCredentials<TCreds>;
+    private rawCredInput;
+    constructor(settings: TSettings, creds?: InferCredentialInput<TCreds>);
+    serializeConfig(): Record<string, unknown>;
+    protected sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    protected withRetry<T>(fn: (signal?: AbortSignal) => Promise<{
+        status: 'done';
+        value: T;
+    } | {
+        status: 'retry';
+    }>, options?: RetryPolicy): Promise<T | null>;
+    abstract sync(options: SyncOptions, storage: StorageHandle, signal?: AbortSignal): Promise<void>;
+}
+declare function defineConnector<TSettings>(): <TCreds extends CredentialsSchema = Record<string, never>>(def: {
+    id: string;
+    credentials?: TCreds;
+    sync: (this: {
+        settings: TSettings;
+        creds: InferCredentials<TCreds>;
+    }, options: SyncOptions, storage: StorageHandle, signal?: AbortSignal) => Promise<void>;
+}) => {
+    new (settings: TSettings, creds?: InferCredentialInput<TCreds>): Connector;
+    readonly id: string;
+    readonly credentials: TCreds | undefined;
+};
+
 interface RetentionConfig {
     maxAge?: number;
     maxSize?: number;
     floor?: number;
     intervalMs?: number;
 }
-interface RetentionCandidates {
+interface RetentionDeletionPlan {
     events: Event[];
-    metrics: Metric[];
+    metrics: MetricSample[];
     distributions: Distribution[];
 }
 declare function selectForDeletion<T>(rows: T[], getTs: (row: T) => number, config: RetentionConfig, nowMs?: number): T[];
-declare function computeRetention(handle: StorageHandle, config: RetentionConfig, nowMs?: number): Promise<RetentionCandidates>;
+declare function computeRetention(handle: StorageHandle, config: RetentionConfig, nowMs?: number): Promise<RetentionDeletionPlan>;
 
 declare const shapeSchema: z.ZodEnum<{
     event: "event";
@@ -90,7 +275,7 @@ declare const groupBySchema: z.ZodObject<{
         month: "month";
     }>;
 }, z.core.$strip>;
-declare const resolvedMetricSchema: z.ZodObject<{
+declare const computedMetricSchema: z.ZodObject<{
     connectorId: z.ZodString;
     shape: z.ZodEnum<{
         event: "event";
@@ -986,7 +1171,7 @@ interface GroupBy {
     field: string;
     granularity: 'hour' | 'day' | 'week' | 'month';
 }
-interface MetricDef {
+interface Metric {
     connector: {
         id: string;
     };
@@ -999,7 +1184,7 @@ interface MetricDef {
     filter?: FilterClause[];
     groupBy?: GroupBy;
 }
-interface ResolvedMetric {
+interface ComputedMetric {
     readonly connectorId: string;
     readonly shape: Shape;
     readonly name?: string;
@@ -1013,7 +1198,7 @@ interface ResolvedMetric {
 interface StatWidget {
     kind: 'stat';
     title: string;
-    metric: ResolvedMetric;
+    metric: ComputedMetric;
     window?: string;
     compare?: 'none' | 'previous-period';
 }
@@ -1025,41 +1210,62 @@ interface StatusWidget {
 interface TimeseriesWidget {
     kind: 'timeseries';
     title: string;
-    metric: ResolvedMetric;
+    metric: ComputedMetric;
     window: string;
     granularity?: 'hour' | 'day' | 'week';
 }
 interface DistributionWidget {
     kind: 'distribution';
     title: string;
-    metric: ResolvedMetric;
+    metric: ComputedMetric;
     window: string;
 }
 type Widget = StatWidget | StatusWidget | TimeseriesWidget | DistributionWidget;
 
-interface ConnectorEntry {
+interface ConfiguredConnector {
     connector: Connector;
 }
 interface Dashboard {
     widgets: Record<string, Widget>;
 }
 interface DashboardConfig {
-    connectors: ConnectorEntry[];
+    connectors: ConfiguredConnector[];
     dashboards: Record<string, Dashboard>;
     retention?: RetentionConfig;
 }
 declare function defineDashboard(options: {
     widgets: Record<string, Widget>;
 }): Dashboard;
-declare function defineMetric(options: MetricDef): ResolvedMetric;
+declare function defineMetric(options: Metric): ComputedMetric;
 declare function defineConfig(config: DashboardConfig): DashboardConfig;
 
+interface CachedWidget {
+    id: string;
+    widgetId: string;
+    connectorId: string;
+    data: unknown;
+    cachedAt: string | null;
+}
+interface SyncState {
+    status: 'idle' | 'syncing' | 'error';
+    lastSyncAt: string | null;
+    lastError: string | null;
+}
+
 type ConfigFieldsSchema = z.ZodObject<z.ZodRawShape>;
 declare function defineConfigFields<T extends z.ZodRawShape>(schema: z.ZodObject<T>): z.ZodObject<T>;
 
-declare function computeMetric(storage: StorageHandle, metric: ResolvedMetric): Promise<unknown>;
+declare function computeMetric(storage: StorageHandle, metric: ComputedMetric): Promise<unknown>;
+
+interface ServerStorage {
+    getStorageHandle(connectorId: string): StorageHandle;
+    getSyncState(): Promise<SyncState>;
+    setSyncing(): Promise<boolean>;
+    setSyncSuccess(): Promise<void>;
+    setSyncError(error: string): Promise<void>;
+}
 
-declare function resolveWidget(id: string, widget: Widget, connectors: ConnectorEntry[] | readonly string[] | undefined, storage: ServerStorage): Promise<WidgetEntry | undefined>;
+declare function resolveWidget(id: string, widget: Widget, connectors: ConfiguredConnector[] | readonly string[] | undefined, storage: ServerStorage): Promise<CachedWidget | undefined>;
 
 declare class InMemoryStorage implements ServerStorage {
     private eventStore;
@@ -1075,4 +1281,4 @@ declare class InMemoryStorage implements ServerStorage {
     setSyncError(error: string): Promise<void>;
 }
 
-export { type AggFn, type ConfigFieldsSchema, Connector, type ConnectorEntry, type Dashboard, type DashboardConfig, Distribution, type DistributionWidget, Event, type FilterClause, type FilterCondition, type FilterOperator, type GroupBy, InMemoryStorage, Metric, type MetricDef, type ResolvedMetric, type RetentionCandidates, type RetentionConfig, ServerStorage, type Shape, type StatWidget, type StatusWidget, StorageHandle, SyncState, type TimeseriesWidget, type Widget, WidgetEntry, type WidgetKind, aggFnSchema, computeMetric, computeRetention, defineConfig, defineConfigFields, defineDashboard, defineMetric, distributionWidgetSchema, filterClauseSchema, filterConditionSchema, filterOperatorSchema, getWidgetSchema, groupBySchema, resolveWidget, resolvedMetricSchema, selectForDeletion, shapeSchema, statWidgetSchema, statusWidgetSchema, timeseriesWidgetSchema, widgetSchema, widgetSchemas };
+export { type AggFn, BaseConnector, type CachedWidget, type ComputedMetric, type ConfigFieldsSchema, type ConfiguredConnector, type Connector, type CredentialField, type CredentialsSchema, type Dashboard, type DashboardConfig, type Distribution, type DistributionQuery, type DistributionWidget, type Edge, type EdgeQuery, type Entity, type EntityQuery, EnvSecretsResolver, type Event, type EventQuery, type FilterClause, type FilterCondition, type FilterOperator, type GroupBy, InMemoryStorage, type InferCredentialInput, type InferCredentials, type JSONValue, type Metric, type MetricQuery, type MetricSample, type RetentionConfig, type RetentionDeletionPlan, type Secret, type SecretsResolver, type ServerStorage, type Shape, type StatWidget, type StatusWidget, type StorageHandle, type SyncOptions, type SyncState, type TimeseriesWidget, type Widget, type WidgetKind, aggFnSchema, computeMetric, computeRetention, computedMetricSchema, defineConfig, defineConfigFields, defineConnector, defineDashboard, defineMetric, distributionWidgetSchema, filterClauseSchema, filterConditionSchema, filterOperatorSchema, getWidgetSchema, groupBySchema, isSecret, resolveSecrets, resolveWidget, secret, selectForDeletion, shapeSchema, statWidgetSchema, statusWidgetSchema, timeseriesWidgetSchema, widgetSchema, widgetSchemas };

package/dist/index.js

@@ -7,7 +7,7 @@ function secret(name) {
   }
   return { $secret: name };
 }
-function isSecretRef(value) {
+function isSecret(value) {
   return typeof value === "object" && value !== null && "$secret" in value && typeof value.$secret === "string";
 }
 var EnvSecretsResolver = class {
@@ -16,8 +16,8 @@ var EnvSecretsResolver = class {
     return env?.[name];
   }
 };
-function resolveSecretRefs(obj, resolver) {
-  if (isSecretRef(obj)) {
+function resolveSecrets(obj, resolver) {
+  if (isSecret(obj)) {
     const name = obj.$secret;
     const value = resolver.resolve(name);
     if (value === void 0) {
@@ -28,13 +28,13 @@ function resolveSecretRefs(obj, resolver) {
     return value;
   }
   if (Array.isArray(obj)) {
-    return obj.map((item) => resolveSecretRefs(item, resolver));
+    return obj.map((item) => resolveSecrets(item, resolver));
   }
   if (typeof obj === "object" && obj !== null) {
     const result = {};
     for (const [key, val] of Object.entries(obj)) {
       Object.defineProperty(result, key, {
-        value: resolveSecretRefs(val, resolver),
+        value: resolveSecrets(val, resolver),
         enumerable: true,
         configurable: true,
         writable: true
@@ -54,7 +54,7 @@ var BaseConnector = class {
   constructor(settings, creds) {
     this.settings = settings;
     this.rawCredInput = creds;
-    this.creds = creds ? resolveSecretRefs(
+    this.creds = creds ? resolveSecrets(
       creds,
       new EnvSecretsResolver()
     ) : {};
@@ -118,10 +118,10 @@ function defineConnector() {
       static credentials = def.credentials;
       id = def.id;
       credentials = def.credentials;
-      async sync(request, storage, signal) {
+      async sync(options, storage, signal) {
         return def.sync.call(
           { settings: this.settings, creds: this.creds },
-          request,
+          options,
           storage,
           signal
         );
@@ -171,7 +171,7 @@ var groupBySchema = z.object({
   field: z.string(),
   granularity: z.enum(["hour", "day", "week", "month"])
 });
-var resolvedMetricSchema = z.object({
+var computedMetricSchema = z.object({
   connectorId: z.string(),
   shape: shapeSchema,
   name: z.string().optional(),
@@ -189,9 +189,9 @@ var titleField = z.string().meta({ label: "Title", description: "Widget title."
 var statWidgetSchema = z.object({
   kind: z.literal("stat"),
   title: titleField,
-  metric: resolvedMetricSchema.meta({
+  metric: computedMetricSchema.meta({
     label: "Metric",
-    description: "Resolved metric definition."
+    description: "Computed metric definition."
   }),
   window: z.string().optional().meta({ label: "Window", description: "Time window, e.g. '7d'." }),
   compare: z.enum(["none", "previous-period"]).default("none").meta({ label: "Compare", description: "Comparison mode." })
@@ -207,9 +207,9 @@ var statusWidgetSchema = z.object({
 var timeseriesWidgetSchema = z.object({
   kind: z.literal("timeseries"),
   title: titleField,
-  metric: resolvedMetricSchema.meta({
+  metric: computedMetricSchema.meta({
     label: "Metric",
-    description: "Resolved metric definition."
+    description: "Computed metric definition."
   }),
   window: z.string().meta({ label: "Window", description: "Time window, e.g. '30d'." }),
   granularity: z.enum(["hour", "day", "week"]).default("day").meta({ label: "Granularity", description: "Time bucket size." })
@@ -217,9 +217,9 @@ var timeseriesWidgetSchema = z.object({
 var distributionWidgetSchema = z.object({
   kind: z.literal("distribution"),
   title: titleField,
-  metric: resolvedMetricSchema.meta({
+  metric: computedMetricSchema.meta({
     label: "Metric",
-    description: "Resolved metric definition."
+    description: "Computed metric definition."
   }),
   window: z.string().meta({ label: "Window", description: "Time window, e.g. '7d'." })
 });
@@ -930,6 +930,7 @@ export {
   aggFnSchema,
   computeMetric,
   computeRetention,
+  computedMetricSchema,
   defineConfig,
   defineConfigFields,
   defineConnector,
@@ -941,10 +942,9 @@ export {
   filterOperatorSchema,
   getWidgetSchema,
   groupBySchema,
-  isSecretRef,
-  resolveSecretRefs,
+  isSecret,
+  resolveSecrets,
   resolveWidget,
-  resolvedMetricSchema,
   secret,
   selectForDeletion,
   shapeSchema,