react-semaphor 0.1.391 → 0.1.393

package/dist/types/dashboard-assistant.d.ts

@@ -907,7 +907,7 @@ declare type SemaphorAnalyticsExecutionResult = {
     intentId?: string;
     queryId?: string;
     status: SemaphorAnalyticsExecutionStatus;
-    resultShape?: SemaphorAnalyticsResult['kind'] | 'period_change';
+    resultShape?: SemaphorAnalyticsExecutionResultShape;
     intent?: SemaphorAnalyticsIntent;
     compiledQuery?: SemaphorCompiledQuery;
     fieldsUsed?: SemaphorExecutionFieldRef[];
@@ -926,6 +926,8 @@ declare type SemaphorAnalyticsExecutionResult = {
     metadata?: Record<string, unknown>;
 };
 
+declare type SemaphorAnalyticsExecutionResultShape = SemaphorAnalyticsResult['kind'] | 'period_change' | 'analysis';
+
 declare type SemaphorAnalyticsExecutionStatus = 'answered' | 'partial' | 'failed';
 
 declare type SemaphorAnalyticsFieldRole = 'measure' | 'date' | 'dimension' | 'input' | 'source' | 'sql';

package/dist/types/data-app-sdk-adapters.d.ts

@@ -71,7 +71,6 @@ declare type SemaphorAnalysisQueryOptions = {
 declare type SemaphorAnalysisQuerySpec = SemaphorMetricQuerySpec & SemaphorAnalysisQueryOptions & {
     analysis?: SemaphorMetricIntent['analysis'];
     timeWindow?: SemaphorMetricIntent['timeWindow'];
-    filters?: SemaphorAnalyticsFilter[];
 };
 
 declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
@@ -478,6 +477,7 @@ declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDeri
     dimensions?: SemaphorQueryField[];
     comparison?: SemaphorMetricComparison;
     orderBy?: SemaphorQueryOrderBy;
+    filters?: SemaphorAnalyticsFilter[];
     inputs?: SemaphorInputReference[];
     relationshipHint?: SemaphorRelationshipHint;
     limit?: number;

package/dist/types/data-app-sdk-validation.d.ts

@@ -314,7 +314,6 @@ export declare type SemaphorAnalysisQueryOptionsValidationResult = {
 declare type SemaphorAnalysisQuerySpec = SemaphorMetricQuerySpec & SemaphorAnalysisQueryOptions & {
     analysis?: SemaphorMetricIntent['analysis'];
     timeWindow?: SemaphorMetricIntent['timeWindow'];
-    filters?: SemaphorAnalyticsFilter[];
 };
 
 export declare type SemaphorAnalysisTimezoneValidator = (tz: string) => string | null;
@@ -364,7 +363,7 @@ declare type SemaphorAnalyticsExecutionResult = {
     intentId?: string;
     queryId?: string;
     status: SemaphorAnalyticsExecutionStatus;
-    resultShape?: SemaphorAnalyticsResult['kind'] | 'period_change';
+    resultShape?: SemaphorAnalyticsExecutionResultShape;
     intent?: SemaphorAnalyticsIntent;
     compiledQuery?: SemaphorCompiledQuery;
     fieldsUsed?: SemaphorExecutionFieldRef[];
@@ -383,6 +382,8 @@ declare type SemaphorAnalyticsExecutionResult = {
     metadata?: Record<string, unknown>;
 };
 
+declare type SemaphorAnalyticsExecutionResultShape = SemaphorAnalyticsResult['kind'] | 'period_change' | 'analysis';
+
 declare type SemaphorAnalyticsExecutionStatus = 'answered' | 'partial' | 'failed';
 
 declare type SemaphorAnalyticsFieldRole = 'measure' | 'date' | 'dimension' | 'input' | 'source' | 'sql';
@@ -955,6 +956,7 @@ declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDeri
     dimensions?: SemaphorQueryField[];
     comparison?: SemaphorMetricComparison;
     orderBy?: SemaphorQueryOrderBy;
+    filters?: SemaphorAnalyticsFilter[];
     inputs?: SemaphorInputReference[];
     relationshipHint?: SemaphorRelationshipHint;
     limit?: number;

package/dist/types/data-app-sdk.d.ts

@@ -408,17 +408,25 @@ export declare type SemaphorAnalysisPayload = {
     answerSummary?: string;
     mode?: string;
     data?: Record<string, unknown>;
-    resultSets?: Record<string, SemaphorAnalysisResultSet>;
+    resultSets?: Partial<Record<SemaphorAnalysisResultSetKey, SemaphorAnalysisResultSet>> & Record<string, SemaphorAnalysisResultSet>;
+    analysisWarnings?: SemaphorAnalysisWarning[];
+    warnings?: unknown[];
     columns?: SemaphorResultColumn[];
     records?: Array<Record<string, unknown>>;
     rowCount?: number;
+    primary?: Array<Record<string, unknown>>;
+    comparison?: unknown;
+    comparisons?: Array<Record<string, unknown>>;
+    contributors?: Array<Record<string, unknown>>;
+    segments?: Array<Record<string, unknown>>;
+    periodChanges?: Array<Record<string, unknown>>;
     changes?: Array<Record<string, unknown>>;
     drivers?: Array<Record<string, unknown>>;
+    absoluteDeltaDrivers?: Array<Record<string, unknown>>;
     largestNegativeChanges?: Array<Record<string, unknown>>;
     largestPositiveChanges?: Array<Record<string, unknown>>;
     largestNegativeDrivers?: Array<Record<string, unknown>>;
     largestPositiveDrivers?: Array<Record<string, unknown>>;
-    comparison?: Record<string, unknown>;
     fieldsUsed?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     querySpec?: Record<string, unknown>;
@@ -447,13 +455,36 @@ export declare type SemaphorAnalysisQueryResult = SemaphorQueryState & SemaphorA
 export declare type SemaphorAnalysisQuerySpec = SemaphorMetricQuerySpec & SemaphorAnalysisQueryOptions & {
     analysis?: SemaphorMetricIntent['analysis'];
     timeWindow?: SemaphorMetricIntent['timeWindow'];
-    filters?: SemaphorAnalyticsFilter[];
 };
 
 export declare type SemaphorAnalysisResultSet = {
+    id?: SemaphorAnalysisResultSetKey | string;
+    role?: SemaphorAnalysisResultSetKey | string;
     records: Array<Record<string, unknown>>;
     columns: SemaphorResultColumn[];
     rowCount?: number;
+    warnings?: SemaphorAnalysisWarning[];
+};
+
+export declare type SemaphorAnalysisResultSetKey = 'primary' | 'comparisons' | 'contributors' | 'segments' | 'periodChanges' | 'records' | 'changes' | 'drivers' | 'absoluteDeltaDrivers' | 'largestNegativeChanges' | 'largestPositiveChanges' | 'largestNegativeDrivers' | 'largestPositiveDrivers';
+
+export declare type SemaphorAnalysisResultSetWarning = {
+    code: 'missing_analysis_result_key';
+    severity: 'warning';
+    message: string;
+    resultSetKey: SemaphorAnalysisResultSetKey | string;
+    rowIndex: number;
+    columnKey: string;
+    columnName?: string;
+    columnLabel?: string;
+    availableKeys: string[];
+};
+
+export declare type SemaphorAnalysisWarning = SemaphorAnalysisResultSetWarning | {
+    code: string;
+    severity?: string;
+    message?: string;
+    [key: string]: unknown;
 };
 
 declare type SemaphorAnalyticsDiagnosticAnsweredItem = {
@@ -501,7 +532,7 @@ declare type SemaphorAnalyticsExecutionResult = {
     intentId?: string;
     queryId?: string;
     status: SemaphorAnalyticsExecutionStatus;
-    resultShape?: SemaphorAnalyticsResult['kind'] | 'period_change';
+    resultShape?: SemaphorAnalyticsExecutionResultShape;
     intent?: SemaphorAnalyticsIntent;
     compiledQuery?: SemaphorCompiledQuery;
     fieldsUsed?: SemaphorExecutionFieldRef[];
@@ -520,6 +551,8 @@ declare type SemaphorAnalyticsExecutionResult = {
     metadata?: Record<string, unknown>;
 };
 
+declare type SemaphorAnalyticsExecutionResultShape = SemaphorAnalyticsResult['kind'] | 'period_change' | 'analysis';
+
 declare type SemaphorAnalyticsExecutionStatus = 'answered' | 'partial' | 'failed';
 
 declare type SemaphorAnalyticsFieldRole = 'measure' | 'date' | 'dimension' | 'input' | 'source' | 'sql';
@@ -666,9 +699,23 @@ export declare type SemaphorDataAppDefinition = {
     views: SemaphorDataAppViewDefinition[];
 };
 
+export declare type SemaphorDataAppDevtoolsIssue = {
+    traceId: string;
+    queryId: string;
+    viewId?: string;
+    viewTitle?: string;
+    queryLabel?: string;
+    severity: 'error' | 'warning';
+    title: string;
+    message: string;
+    code?: string;
+    path?: string;
+};
+
 export declare type SemaphorDataAppDevtoolsState = {
     enabled: boolean;
     queries: SemaphorDataAppTrace[];
+    issues: SemaphorDataAppDevtoolsIssue[];
     getQuery(queryId: string): SemaphorDataAppTrace | undefined;
     getQueries(queryId: string): SemaphorDataAppTrace[];
 };
@@ -683,6 +730,7 @@ export declare type SemaphorDataAppDevtoolsWindowBridge = {
     snapshot(): SemaphorDataAppDevtoolsState;
     getQuery(queryId: string): SemaphorDataAppTrace | undefined;
     getQueries(queryId: string): SemaphorDataAppTrace[];
+    getIssues(): SemaphorDataAppDevtoolsIssue[];
 };
 
 export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, debug, children, }: SemaphorDataAppProviderProps): JSX.Element;
@@ -693,6 +741,15 @@ export declare type SemaphorDataAppProviderProps = SemaphorQueryExecutorContext
     children: ReactNode;
 };
 
+export declare type SemaphorDataAppQueryError = Error & {
+    kind: 'data_app_query_error';
+    requestId?: string;
+    details?: unknown;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+    validation?: SemaphorAnalyticsValidationResult;
+    validationIssues?: SemaphorAnalyticsValidationIssue[];
+};
+
 export declare type SemaphorDataAppSourceHint = {
     file?: string;
     line?: number;
@@ -1266,6 +1323,7 @@ export declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & Semaphor
     dimensions?: SemaphorQueryField[];
     comparison?: SemaphorMetricComparison;
     orderBy?: SemaphorQueryOrderBy;
+    filters?: SemaphorAnalyticsFilter[];
     inputs?: SemaphorInputReference[];
     relationshipHint?: SemaphorRelationshipHint;
     limit?: number;
@@ -1377,8 +1435,18 @@ export declare type SemaphorQuerySourceSpec = {
 
 export declare type SemaphorQueryState = {
     status: SemaphorQueryStatus;
+    executionStatus?: SemaphorAnalyticsExecutionStatus;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+    validation?: SemaphorAnalyticsValidationResult;
+    coverage?: SemaphorAnalyticsExecutionResult['coverage'];
+    diagnosticFeedback?: SemaphorAnalyticsExecutionResult['diagnosticFeedback'];
     isLoading: boolean;
-    error: Error | null;
+    isEmpty: boolean;
+    isPartial: boolean;
+    isFiltered: boolean;
+    isStale: boolean;
+    isValidated: boolean;
+    error: SemaphorDataAppQueryError | null;
     trace?: SemaphorDataAppTrace;
 };
 

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.391",
+  "version": "0.1.393",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -218,6 +218,7 @@
     "tailwind-merge": "^2.1.0",
     "tailwindcss-animate": "^1.0.7",
     "uuid": "^9.0.1",
+    "zod": "^3.25.76",
     "zustand": "^5.0.9"
   },
   "peerDependencies": {

package/src/data-app-sdk/README.md

@@ -65,6 +65,61 @@ const result = useSemaphorQuery(revenueBySegment, {
 });
 ```
 
+## Query State
+
+`useSemaphorQuery` returns normal loading/error fields plus the governed
+Semaphor execution result fields. Generated apps should branch on these public
+fields instead of inspecting nested payload internals.
+
+```tsx
+const result = useSemaphorQuery(revenueBySegment, {
+  inputs: [segmentHandle],
+});
+
+if (result.isLoading && !result.isStale) return <Spinner />;
+if (result.isStale) return <Table rows={result.records} subdued />;
+
+if (result.status === "error") {
+  return (
+    <ErrorPanel
+      message={result.error?.message ?? "Query failed"}
+      issues={result.validation?.errors ?? result.error?.validationIssues ?? []}
+    />
+  );
+}
+
+if (result.isEmpty) return <EmptyState />;
+
+return (
+  <>
+    {result.isPartial ? <WarningBanner issues={result.coverage?.warnings} /> : null}
+    {result.isFiltered ? <FilterIndicator /> : null}
+    {result.isValidated ? <ValidationBadge status={result.executionStatus} /> : null}
+    <Table rows={result.records} />
+  </>
+);
+```
+
+Important state fields:
+
+- `executionStatus`: governed execution status, usually `answered`, `partial`,
+  or `failed` when the server or SDK produced an execution result.
+- `executionResult`: full `SemaphorAnalyticsExecutionResult` for audit,
+  diagnostics, coverage, and result metadata.
+- `validation`, `coverage`, and `diagnosticFeedback`: top-level aliases from
+  `executionResult` or structured SDK validation errors.
+- `isEmpty`: successful query returned no meaningful rows/options/cells/value.
+- `isPartial`: execution status, coverage, diagnostic feedback, or row-limit
+  metadata says the result is incomplete.
+- `isFiltered`: one or more active filter inputs were applied to the query.
+- `isStale`: previous successful data is being shown while newer inputs load.
+- `isValidated`: validation metadata is present.
+
+Validation failures produce a structured `SemaphorDataAppQueryError` in
+`result.error`, with `kind: "data_app_query_error"`, `validation`,
+`validationIssues`, and `executionResult` when available. DevTools traces expose
+the same execution status and structured issues.
+
 ## Source And Fields
 
 ```tsx

package/dist/chunks/analyze-result-contract-CtXfp3nv.js

@@ -1 +0,0 @@
-"use strict";const t={answerSummary:"string",responseDetail:"responseDetail",mode:"string",comparisonType:"string",executionResult:"unknown",compiledQuery:"unknown",data:"unknown",resultSets:"record",columns:"unknownArray",records:"recordArray",rowCount:"number",rowLimitExceeded:"boolean",output:"string",querySpec:"unknown",metadata:"record",validation:"unknown",coverage:"unknown",diagnosticFeedback:"unknown",missingFields:"stringArray",warnings:"unknownArray",comparison:"unknown",population:"unknown",comparisons:"recordArray",fieldsUsed:"unknown",changes:"recordArray",largestNegativeChanges:"recordArray",largestPositiveChanges:"recordArray",drivers:"recordArray",absoluteDeltaDrivers:"recordArray",largestNegativeDrivers:"recordArray",largestPositiveDrivers:"recordArray",periodRows:"recordArray",sql:"unknown",omitted:"stringArray"},u=new Set(Object.keys(t)),y=new Set(["compact","standard","debug"]);function d(){return Object.keys(t)}function c(r){return u.has(r)}function A(r){if(!r||typeof r!="object"||Array.isArray(r))throw new Error("Semaphor analyze result must be an object.");const e=r,n=Object.keys(e).filter(o=>!c(o));if(n.length)throw new Error(`Semaphor analyze result contains unsupported top-level field(s): ${n.join(", ")}.`);for(const[o,s]of Object.entries(e)){if(s===void 0)continue;const a=t[o];if(!l(s,a))throw new Error(`Semaphor analyze result field "${o}" does not match contract kind "${a}".`)}return e}function l(r,e){switch(e){case"boolean":return typeof r=="boolean";case"number":return typeof r=="number"&&Number.isFinite(r);case"record":return i(r);case"recordArray":return Array.isArray(r)&&r.every(i);case"responseDetail":return typeof r=="string"&&y.has(r);case"string":return typeof r=="string";case"stringArray":return Array.isArray(r)&&r.every(n=>typeof n=="string");case"unknown":return!0;case"unknownArray":return Array.isArray(r)}}function i(r){return!!(r&&typeof r=="object"&&!Array.isArray(r))}exports.SEMAPHOR_ANALYZE_RESULT_FIELD_CONTRACT=t;exports.getSemaphorAnalyzeResultFieldNames=d;exports.isSemaphorAnalyzeResultFieldName=c;exports.parseSemaphorAnalyzeResult=A;

package/dist/chunks/analyze-result-contract-DuhlklhI.js

@@ -1,102 +0,0 @@
-const t = {
-  answerSummary: "string",
-  responseDetail: "responseDetail",
-  mode: "string",
-  comparisonType: "string",
-  executionResult: "unknown",
-  compiledQuery: "unknown",
-  data: "unknown",
-  resultSets: "record",
-  columns: "unknownArray",
-  records: "recordArray",
-  rowCount: "number",
-  rowLimitExceeded: "boolean",
-  output: "string",
-  querySpec: "unknown",
-  metadata: "record",
-  validation: "unknown",
-  coverage: "unknown",
-  diagnosticFeedback: "unknown",
-  missingFields: "stringArray",
-  warnings: "unknownArray",
-  comparison: "unknown",
-  population: "unknown",
-  comparisons: "recordArray",
-  fieldsUsed: "unknown",
-  changes: "recordArray",
-  largestNegativeChanges: "recordArray",
-  largestPositiveChanges: "recordArray",
-  drivers: "recordArray",
-  absoluteDeltaDrivers: "recordArray",
-  largestNegativeDrivers: "recordArray",
-  largestPositiveDrivers: "recordArray",
-  periodRows: "recordArray",
-  sql: "unknown",
-  omitted: "stringArray"
-}, c = new Set(
-  Object.keys(t)
-), u = /* @__PURE__ */ new Set([
-  "compact",
-  "standard",
-  "debug"
-]);
-function A() {
-  return Object.keys(
-    t
-  );
-}
-function y(r) {
-  return c.has(r);
-}
-function l(r) {
-  if (!r || typeof r != "object" || Array.isArray(r))
-    throw new Error("Semaphor analyze result must be an object.");
-  const e = r, n = Object.keys(e).filter(
-    (o) => !y(o)
-  );
-  if (n.length)
-    throw new Error(
-      `Semaphor analyze result contains unsupported top-level field(s): ${n.join(", ")}.`
-    );
-  for (const [o, s] of Object.entries(e)) {
-    if (s === void 0)
-      continue;
-    const a = t[o];
-    if (!d(s, a))
-      throw new Error(
-        `Semaphor analyze result field "${o}" does not match contract kind "${a}".`
-      );
-  }
-  return e;
-}
-function d(r, e) {
-  switch (e) {
-    case "boolean":
-      return typeof r == "boolean";
-    case "number":
-      return typeof r == "number" && Number.isFinite(r);
-    case "record":
-      return i(r);
-    case "recordArray":
-      return Array.isArray(r) && r.every(i);
-    case "responseDetail":
-      return typeof r == "string" && u.has(r);
-    case "string":
-      return typeof r == "string";
-    case "stringArray":
-      return Array.isArray(r) && r.every((n) => typeof n == "string");
-    case "unknown":
-      return !0;
-    case "unknownArray":
-      return Array.isArray(r);
-  }
-}
-function i(r) {
-  return !!(r && typeof r == "object" && !Array.isArray(r));
-}
-export {
-  t as S,
-  A as g,
-  y as i,
-  l as p
-};