react-semaphor 0.1.345 → 0.1.346

package/dist/data-app-sdk/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const S=require("../chunks/validators-8R9pr2K9.js"),K=require("../chunks/index-BxM99sFL.js"),a=require("react"),F=require("react/jsx-runtime");function E(e){var r;const t=V(e);return{version:1,kind:"metric",id:e.id,label:e.label,source:D(e),metrics:t,primaryMetric:z(e,t),dateField:e.dateField?l(e.dateField,"date"):void 0,timeGrain:e.timeGrain,dimensions:(r=e.dimensions)==null?void 0:r.map(n=>l(n,"dimension")),comparison:X(e.comparison),orderBy:e.orderBy?{field:l(e.orderBy.field),direction:e.orderBy.direction}:void 0,inputs:k(e.inputs),limit:e.limit}}function z(e,t){if(!e.primaryMetric)return t[0]||{name:"",role:"measure"};const r=l(e.primaryMetric,"measure"),n=Q(r,t),o=n.length===1?n[0]:void 0;return o?B(r,o):r}function V(e){const t=[];for(const r of e.metrics.map(n=>l(n,"measure"))){if(!r.name)continue;const n=t.findIndex(o=>j(o,r));if(n===-1){t.push(r);continue}t[n]=B(t[n],r)}return t}function j(e,t){return S.semaphorFieldRefsMatch(e,t)&&g(e)===g(t)}function N(e,t){return g(t)===g(e)}function L(e,t){return t.name!==e.name||e.source&&!S.semaphorFieldRefsMatch(t,e)?!1:N(e,t)}function Q(e,t){const r=t.filter(n=>L(e,n));return e.aggregate!==void 0,r}function g(e){return(e.aggregate||"SUM").toUpperCase()}function B(e,t){if(e.aggregate&&t.aggregate&&e.aggregate!==t.aggregate)throw new Error(`Metric "${e.name}" was requested with conflicting aggregate semantics: ${e.aggregate} and ${t.aggregate}.`);return{...S.preferSemaphorFieldRefMetadata(e,t),aggregate:e.aggregate||t.aggregate}}function w(e){if("sort"in e)throw new Error("useSemaphorRecords supports orderBy for a single deterministic sort. Multiple sort clauses are not supported by the analytics protocol yet.");if(!W(e))throw new Error("useSemaphorRecords needs at least one field.");const t=G(e.fields);return{version:1,kind:"records",id:e.id,label:e.label,source:D(e),fields:t,dateField:e.dateField?l(e.dateField,"date"):void 0,timeGrain:e.timeGrain,orderBy:e.orderBy?{field:l(e.orderBy.field),direction:e.orderBy.direction}:void 0,inputs:k(e.inputs),limit:e.limit}}function G(e){return e.map(t=>{const r=l(t);if(!r.role)throw new Error(`useSemaphorRecords field "${r.name}" needs an explicit role.`);return r})}function O(e){return{version:1,kind:"inputOptions",id:e.id,label:e.label,source:D(e),field:l(e.field,"dimension"),search:e.search,limit:e.limit}}function $(e){if("toAnalyticsInput"in e){const t=e.toAnalyticsInput();return{inputId:t.inputId,...t.field?{field:t.field}:{}}}return{inputId:e.inputId,...e.field?{field:e.field}:{}}}function J(e){const t=k(e);return t.length>0?t:void 0}function q(e){return(e||[]).map(H)}function M(e){return q(e).filter(t=>t.isActive)}function C(e){return e.kind==="filter"?{inputId:e.id,kind:e.kind,label:e.label,field:l(e.field,"dimension"),operator:e.operator||"in"}:{inputId:e.id,kind:e.kind,label:e.label}}function T(e=[]){return e.map(t=>typeof t=="object"?t:{label:String(t),value:t})}function y(e){return e==null?!1:Array.isArray(e)?e.length>0:typeof e=="string"?e.trim().length>0:!0}function H(e){return"toAnalyticsInput"in e?e.toAnalyticsInput():"kind"in e&&"isActive"in e?e:{...e,kind:"filter",isActive:y(e.value),value:e.value}}function D(e){return e.source}function W(e){var t;return!!((t=e.fields)!=null&&t.length)}function l(e,t){return{...e,role:e.role||t}}function k(e){return(e||[]).map($)}function X(e){if(e)return e}function P(){return{executeMetric:(e,t)=>v(e,t),executeRecords:(e,t)=>v(e,t),executeInputOptions:(e,t)=>v(e,t)}}async function v(e,t){if(!t.token)throw new Error("SemaphorDataAppProvider needs a token to execute queries.");const r=await fetch(ee(t),{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${t.token}`},body:JSON.stringify({intent:e,activeInputs:t.activeInputs,resultShape:e.kind})}),n=await Y(r);if(!r.ok||n.error)throw new Error(n.error||`Semaphor Data App execution failed with status ${r.status}.`);return n}async function Y(e){const t=await e.text().catch(()=>"");if(!t.trim())return e.ok?{error:"Semaphor Data App execution returned an empty response."}:{};try{return JSON.parse(t)}catch{return e.ok?{error:"Semaphor Data App execution returned invalid JSON.",details:t}:{error:Z(e,t),details:t}}}function Z(e,t){const r=e.statusText?` ${e.statusText}`:"",n=t.replace(/\s+/g," ").trim();return n?`Semaphor Data App execution failed with status ${e.status}${r}: ${n.slice(0,240)}`:`Semaphor Data App execution failed with status ${e.status}${r}.`}function ee(e){const t=te(e).replace(/\/+$/,"");return t?t.endsWith("/api")?`${t}/v1/data-app/execute`:`${t}/api/v1/data-app/execute`:"/api/v1/data-app/execute"}function te(e){if(e.apiBaseUrl)return e.apiBaseUrl;if(!e.token)return"";try{return K.jwtDecode(e.token).apiServiceUrl||""}catch{return""}}const R=a.createContext({});function U(){if(!(typeof window>"u"))return window.__SEMAPHOR_DATA_APP_RUNTIME__}function _(){return a.useContext(R)}function re({token:e,apiBaseUrl:t,executor:r,children:n}){var d;const o=U(),u=((d=o==null?void 0:o.authToken)==null?void 0:d.accessToken)||e,i=(o==null?void 0:o.dataApiBaseUrl)||(o==null?void 0:o.apiBaseUrl)||t,m=a.useMemo(()=>P(),[]),s=r||m,p=a.useMemo(()=>({token:u,apiBaseUrl:i,executor:s}),[i,s,u]);return F.jsx(R.Provider,{value:p,children:n})}const I={value:null},ne={records:[]},A={options:[]};function oe(e){const t=M(e.inputs);try{const r=E(e),n=b(r);return n?{error:n,activeInputs:t,queryKey:c(void 0,t,n),idleData:I}:{intent:r,error:null,activeInputs:t,queryKey:c(r,t),idleData:I}}catch(r){const n=h(r);return{error:n,activeInputs:t,queryKey:c(void 0,t,n),idleData:I}}}function ie(e){const t=M(e.inputs),r=ne;try{const n=w(e),o=b(n);return o?{error:o,activeInputs:t,queryKey:c(void 0,t,o),idleData:r}:{intent:n,error:null,activeInputs:t,queryKey:c(n,t),idleData:r}}catch(n){const o=h(n);return{error:o,activeInputs:t,queryKey:c(void 0,t,o),idleData:r}}}function ae(e){try{const t=O(e),r=b(t);return r?{error:r,queryKey:c(void 0,void 0,r),idleData:A}:{intent:t,error:null,queryKey:c(t),idleData:A}}catch(t){const r=h(t);return{error:r,queryKey:c(void 0,void 0,r),idleData:A}}}function h(e){return e instanceof Error?e:new Error(String(e))}function b(e){const t=S.validateSemaphorAnalyticsIntent(e);if(t.ok)return null;const r=t.errors.map(n=>n.path?`${n.code} at ${n.path}: ${n.message}`:`${n.code}: ${n.message}`).join("; ");return new Error(`Invalid Semaphor analytics intent. ${r}`)}function c(e,t,r){return JSON.stringify({intent:e,activeInputs:t,error:r==null?void 0:r.message})}function ue(e){const[t,r]=a.useState(e.defaultValue),n=Object.prototype.hasOwnProperty.call(e,"value"),o=n?e.value:t,u=a.useMemo(()=>T(e.options),[e.options]),i=a.useCallback(s=>{var d;const p=s;(d=e.onValueChange)==null||d.call(e,p),n||r(p)},[n,e]),m=a.useCallback(()=>i(void 0),[i]);return a.useMemo(()=>{const s=C(e);return{id:e.id,kind:e.kind,label:e.label,field:s.field,operator:s.operator,controlRole:e.kind==="control"?e.role:void 0,value:o,options:u,isActive:y(o),setValue:i,clear:m,toAnalyticsInput:()=>({inputId:s.inputId,field:s.field,kind:e.kind,label:e.label,value:o,isActive:y(o),operator:s.operator,controlRole:e.kind==="control"?e.role:void 0})}},[m,u,i,e,o])}function se(e){const t=a.useMemo(()=>oe(e),[e]),r=a.useCallback(u=>{var i;return t.intent?(i=u.executor)==null?void 0:i.executeMetric(t.intent,u):void 0},[t.intent]),n=x(t.queryKey,r,t.idleData,t.activeInputs),o=t.error?t.idleData:n.data;return{id:e.id,intent:t.intent,value:(o==null?void 0:o.value)??null,metrics:o==null?void 0:o.metrics,comparisonValue:o==null?void 0:o.comparisonValue,delta:o==null?void 0:o.delta,deltaPercent:o==null?void 0:o.deltaPercent,records:o==null?void 0:o.records,status:t.error?"error":n.status,isLoading:!t.error&&n.status==="loading",error:t.error||n.error}}function le(e){const t=a.useMemo(()=>ie(e),[e]),r=a.useCallback(u=>{var i;return t.intent?(i=u.executor)==null?void 0:i.executeRecords(t.intent,u):void 0},[t.intent]),n=x(t.queryKey,r,t.idleData,t.activeInputs),o=t.error?t.idleData:n.data;return{id:e.id,intent:t.intent,records:(o==null?void 0:o.records)||[],columns:o==null?void 0:o.columns,rowCount:o==null?void 0:o.rowCount,status:t.error?"error":n.status,isLoading:!t.error&&n.status==="loading",error:t.error||n.error}}function de(e){const t=a.useMemo(()=>ae(e),[e]),r=a.useCallback(u=>{var i;return t.intent?(i=u.executor)==null?void 0:i.executeInputOptions(t.intent,u):void 0},[t.intent]),n=x(t.queryKey,r,t.idleData),o=t.error?t.idleData:n.data;return{id:e.id,intent:t.intent,options:(o==null?void 0:o.options)||[],status:t.error?"error":n.status,isLoading:!t.error&&n.status==="loading",error:t.error||n.error}}function x(e,t,r,n){const o=_(),u=a.useRef(t),i=a.useRef(n),[m,s]=a.useState({status:"idle",data:r,error:null});return u.current=t,i.current=n,a.useEffect(()=>{let p;try{p=u.current({...o,activeInputs:i.current})}catch(f){s({status:"error",data:r,error:h(f)});return}if(!p){s({status:"idle",data:r,error:null});return}let d=!1;return s(f=>({status:"loading",data:f.data,error:null})),p.then(f=>{d||s({status:"success",data:f,error:null})}).catch(f=>{d||s({status:"error",data:r,error:h(f)})}),()=>{d=!0}},[r,e,o]),m}exports.SemaphorDataAppContext=R;exports.SemaphorDataAppProvider=re;exports.createSemaphorDataAppExecutor=P;exports.hasSemaphorInputValue=y;exports.normalizeSemaphorInputOptions=T;exports.readWindowRuntime=U;exports.toSemaphorActiveInputSnapshots=M;exports.toSemaphorInputBinding=$;exports.toSemaphorInputBindings=J;exports.toSemaphorInputOptionsIntent=O;exports.toSemaphorInputSnapshots=q;exports.toSemaphorInputSpec=C;exports.toSemaphorMetricIntent=E;exports.toSemaphorRecordsIntent=w;exports.useSemaphorDataAppRuntime=_;exports.useSemaphorInput=ue;exports.useSemaphorInputOptions=de;exports.useSemaphorMetric=se;exports.useSemaphorRecords=le;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const S=require("../chunks/validators-8R9pr2K9.js"),K=require("../chunks/index-BxM99sFL.js"),a=require("react"),F=require("react/jsx-runtime");function E(e){var r;const t=V(e);return{version:1,kind:"metric",id:e.id,label:e.label,source:k(e),metrics:t,primaryMetric:z(e,t),dateField:e.dateField?l(e.dateField,"date"):void 0,timeGrain:e.timeGrain,dimensions:(r=e.dimensions)==null?void 0:r.map(n=>l(n,"dimension")),comparison:X(e.comparison),orderBy:e.orderBy?{field:l(e.orderBy.field),direction:e.orderBy.direction}:void 0,inputs:R(e.inputs),limit:e.limit}}function z(e,t){if(!e.primaryMetric)return t[0]||{name:"",role:"measure"};const r=l(e.primaryMetric,"measure"),n=L(r,t),o=n.length===1?n[0]:void 0;return o?B(r,o):r}function V(e){const t=[];for(const r of e.metrics.map(n=>l(n,"measure"))){if(!r.name)continue;const n=t.findIndex(o=>j(o,r));if(n===-1){t.push(r);continue}t[n]=B(t[n],r)}return t}function j(e,t){return S.semaphorFieldRefsMatch(e,t)&&g(e)===g(t)}function N(e,t){return g(t)===g(e)}function Q(e,t){return t.name!==e.name||e.source&&!S.semaphorFieldRefsMatch(t,e)?!1:N(e,t)}function L(e,t){const r=t.filter(n=>Q(e,n));return e.aggregate!==void 0,r}function g(e){return(e.aggregate||"SUM").toUpperCase()}function B(e,t){if(e.aggregate&&t.aggregate&&e.aggregate!==t.aggregate)throw new Error(`Metric "${e.name}" was requested with conflicting aggregate semantics: ${e.aggregate} and ${t.aggregate}.`);return{...S.preferSemaphorFieldRefMetadata(e,t),aggregate:e.aggregate||t.aggregate}}function w(e){if("sort"in e)throw new Error("useSemaphorRecords supports orderBy for a single deterministic sort. Multiple sort clauses are not supported by the analytics protocol yet.");if(!W(e))throw new Error("useSemaphorRecords needs at least one field.");const t=G(e.fields);return{version:1,kind:"records",id:e.id,label:e.label,source:k(e),fields:t,dateField:e.dateField?l(e.dateField,"date"):void 0,timeGrain:e.timeGrain,orderBy:e.orderBy?{field:l(e.orderBy.field),direction:e.orderBy.direction}:void 0,inputs:R(e.inputs),limit:e.limit}}function G(e){return e.map(t=>{const r=l(t);if(!r.role)throw new Error(`useSemaphorRecords field "${r.name}" needs an explicit role.`);return r})}function O(e){return{version:1,kind:"inputOptions",id:e.id,label:e.label,source:k(e),field:l(e.field,"dimension"),search:e.search,limit:e.limit}}function $(e){if("toAnalyticsInput"in e){const t=e.toAnalyticsInput();return{inputId:t.inputId,...t.field?{field:t.field}:{}}}return{inputId:e.inputId,...e.field?{field:e.field}:{}}}function J(e){const t=R(e);return t.length>0?t:void 0}function q(e){return(e||[]).map(H)}function M(e){return q(e).filter(t=>t.isActive)}function C(e){return e.kind==="filter"?{inputId:e.id,kind:e.kind,label:e.label,field:l(e.field,"dimension"),operator:e.operator||"in"}:{inputId:e.id,kind:e.kind,label:e.label}}function T(e=[]){return e.map(t=>typeof t=="object"?t:{label:String(t),value:t})}function y(e){return e==null?!1:Array.isArray(e)?e.length>0:typeof e=="string"?e.trim().length>0:!0}function H(e){return"toAnalyticsInput"in e?e.toAnalyticsInput():"kind"in e&&"isActive"in e?e:{...e,kind:"filter",isActive:y(e.value),value:e.value}}function k(e){return e.source}function W(e){var t;return!!((t=e.fields)!=null&&t.length)}function l(e,t){return{...e,role:e.role||t}}function R(e){return(e||[]).map($)}function X(e){if(e)return e}function P(){return{executeMetric:(e,t)=>v(e,t),executeRecords:(e,t)=>v(e,t),executeInputOptions:(e,t)=>v(e,t)}}async function v(e,t){if(!t.token)throw new Error("SemaphorDataAppProvider needs a token to execute queries.");const r=await fetch(ee(t),{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${t.token}`},body:JSON.stringify({intent:e,activeInputs:t.activeInputs,resultShape:e.kind})}),n=await Y(r);if(!r.ok||n.error)throw new Error(n.error||`Semaphor Data App execution failed with status ${r.status}.`);return n}async function Y(e){const t=await e.text().catch(()=>"");if(!t.trim())return e.ok?{error:"Semaphor Data App execution returned an empty response."}:{};try{return JSON.parse(t)}catch{return e.ok?{error:"Semaphor Data App execution returned invalid JSON.",details:t}:{error:Z(e,t),details:t}}}function Z(e,t){const r=e.statusText?` ${e.statusText}`:"",n=t.replace(/\s+/g," ").trim();return n?`Semaphor Data App execution failed with status ${e.status}${r}: ${n.slice(0,240)}`:`Semaphor Data App execution failed with status ${e.status}${r}.`}function ee(e){const t=te(e).replace(/\/+$/,"");return t?t.endsWith("/api")?`${t}/v1/data-app/execute`:`${t}/api/v1/data-app/execute`:"/api/v1/data-app/execute"}function te(e){if(e.apiBaseUrl)return e.apiBaseUrl;if(!e.token)return"";try{return K.jwtDecode(e.token).apiServiceUrl||""}catch{return""}}const D=a.createContext({});function U(){if(!(typeof window>"u"))return window.__SEMAPHOR_DATA_APP_RUNTIME__}function _(){return a.useContext(D)}function re({token:e,apiBaseUrl:t,executor:r,children:n}){var d;const o=U(),u=((d=o==null?void 0:o.authToken)==null?void 0:d.accessToken)||e,i=(o==null?void 0:o.dataApiBaseUrl)||(o==null?void 0:o.apiBaseUrl)||t,m=a.useMemo(()=>P(),[]),s=r||m,f=a.useMemo(()=>({token:u,apiBaseUrl:i,executor:s}),[i,s,u]);return F.jsx(D.Provider,{value:f,children:n})}const I={value:null},ne={records:[]},A={options:[]};function oe(e){const t=M(e.inputs);try{const r=E(e),n=b(r);return n?{error:n,activeInputs:t,queryKey:c(void 0,t,n),idleData:I}:{intent:r,error:null,activeInputs:t,queryKey:c(r,t),idleData:I}}catch(r){const n=h(r);return{error:n,activeInputs:t,queryKey:c(void 0,t,n),idleData:I}}}function ie(e){const t=M(e.inputs),r=ne;try{const n=w(e),o=b(n);return o?{error:o,activeInputs:t,queryKey:c(void 0,t,o),idleData:r}:{intent:n,error:null,activeInputs:t,queryKey:c(n,t),idleData:r}}catch(n){const o=h(n);return{error:o,activeInputs:t,queryKey:c(void 0,t,o),idleData:r}}}function ae(e){try{const t=O(e),r=b(t);return r?{error:r,queryKey:c(void 0,void 0,r),idleData:A}:{intent:t,error:null,queryKey:c(t),idleData:A}}catch(t){const r=h(t);return{error:r,queryKey:c(void 0,void 0,r),idleData:A}}}function h(e){return e instanceof Error?e:new Error(String(e))}function b(e){const t=S.validateSemaphorAnalyticsIntent(e);if(t.ok)return null;const r=t.errors.map(n=>n.path?`${n.code} at ${n.path}: ${n.message}`:`${n.code}: ${n.message}`).join("; ");return new Error(`Invalid Semaphor analytics intent. ${r}`)}function c(e,t,r){return JSON.stringify({intent:e,activeInputs:t,error:r==null?void 0:r.message})}function ue(e){const[t,r]=a.useState(e.defaultValue),n=Object.prototype.hasOwnProperty.call(e,"value"),o=n?e.value:t,u=a.useMemo(()=>T(e.options),[e.options]),i=a.useCallback(s=>{var d;const f=s;(d=e.onValueChange)==null||d.call(e,f),n||r(f)},[n,e]),m=a.useCallback(()=>i(void 0),[i]);return a.useMemo(()=>{const s=C(e);return{id:e.id,kind:e.kind,label:e.label,field:s.field,operator:s.operator,controlRole:e.kind==="control"?e.role:void 0,value:o,options:u,isActive:y(o),setValue:i,clear:m,toAnalyticsInput:()=>({inputId:s.inputId,field:s.field,kind:e.kind,label:e.label,value:o,isActive:y(o),operator:s.operator,controlRole:e.kind==="control"?e.role:void 0})}},[m,u,i,e,o])}function se(e){const t=a.useMemo(()=>oe(e),[e]),r=a.useCallback(u=>{var i;return t.intent?(i=u.executor)==null?void 0:i.executeMetric(t.intent,u):void 0},[t.intent]),n=x(t.queryKey,r,t.idleData,t.activeInputs),o=t.error?t.idleData:n.data;return{id:e.id,intent:t.intent,value:(o==null?void 0:o.value)??null,metrics:o==null?void 0:o.metrics,comparisonValue:o==null?void 0:o.comparisonValue,delta:o==null?void 0:o.delta,deltaPercent:o==null?void 0:o.deltaPercent,records:o==null?void 0:o.records,status:t.error?"error":n.status,isLoading:!t.error&&n.status==="loading",error:t.error||n.error}}function le(e){const t=a.useMemo(()=>ie(e),[e]),r=a.useCallback(u=>{var i;return t.intent?(i=u.executor)==null?void 0:i.executeRecords(t.intent,u):void 0},[t.intent]),n=x(t.queryKey,r,t.idleData,t.activeInputs),o=t.error?t.idleData:n.data;return{id:e.id,intent:t.intent,records:(o==null?void 0:o.records)||[],columns:o==null?void 0:o.columns,rowCount:o==null?void 0:o.rowCount,status:t.error?"error":n.status,isLoading:!t.error&&n.status==="loading",error:t.error||n.error}}function de(e){const t=a.useMemo(()=>ae(e),[e]),r=a.useCallback(u=>{var i;return t.intent?(i=u.executor)==null?void 0:i.executeInputOptions(t.intent,u):void 0},[t.intent]),n=x(t.queryKey,r,t.idleData),o=t.error?t.idleData:n.data;return{id:e.id,intent:t.intent,options:(o==null?void 0:o.options)||[],status:t.error?"error":n.status,isLoading:!t.error&&n.status==="loading",error:t.error||n.error}}function x(e,t,r,n){const o=_(),u=a.useRef(t),i=a.useRef(n),[m,s]=a.useState({status:"idle",data:r,error:null});return u.current=t,i.current=n,a.useEffect(()=>{let f;try{f=u.current({...o,activeInputs:i.current})}catch(p){s({status:"error",data:r,error:h(p)});return}if(!f){s({status:"idle",data:r,error:null});return}let d=!1;return s(p=>({status:"loading",data:p.data,error:null})),f.then(p=>{d||s({status:"success",data:p,error:null})}).catch(p=>{d||s({status:"error",data:r,error:h(p)})}),()=>{d=!0}},[r,e,o]),m}exports.SemaphorDataAppContext=D;exports.SemaphorDataAppProvider=re;exports.createSemaphorQueryExecutor=P;exports.hasSemaphorInputValue=y;exports.normalizeSemaphorInputOptions=T;exports.readWindowRuntime=U;exports.toSemaphorActiveInputSnapshots=M;exports.toSemaphorInputBinding=$;exports.toSemaphorInputBindings=J;exports.toSemaphorInputOptionsIntent=O;exports.toSemaphorInputSnapshots=q;exports.toSemaphorInputSpec=C;exports.toSemaphorMetricIntent=E;exports.toSemaphorRecordsIntent=w;exports.useSemaphorDataAppRuntime=_;exports.useSemaphorInput=ue;exports.useSemaphorInputOptions=de;exports.useSemaphorMetric=se;exports.useSemaphorRecords=le;

package/dist/data-app-sdk/index.js

@@ -10,7 +10,7 @@ function P(t) {
     kind: "metric",
     id: t.id,
     label: t.label,
-    source: D(t),
+    source: k(t),
     metrics: e,
     primaryMetric: F(t, e),
     dateField: t.dateField ? s(t.dateField, "date") : void 0,
@@ -21,7 +21,7 @@ function P(t) {
       field: s(t.orderBy.field),
       direction: t.orderBy.direction
     } : void 0,
-    inputs: k(t.inputs),
+    inputs: D(t.inputs),
     limit: t.limit
   };
 }
@@ -48,10 +48,10 @@ function z(t) {
   return e;
 }
 function V(t, e) {
-  return x(t, e) && y(t) === y(e);
+  return x(t, e) && g(t) === g(e);
 }
 function j(t, e) {
-  return y(e) === y(t);
+  return g(e) === g(t);
 }
 function N(t, e) {
   return e.name !== t.name || t.source && !x(e, t) ? !1 : j(t, e);
@@ -62,7 +62,7 @@ function L(t, e) {
   );
   return t.aggregate !== void 0, r;
 }
-function y(t) {
+function g(t) {
   return (t.aggregate || "SUM").toUpperCase();
 }
 function w(t, e) {
@@ -90,7 +90,7 @@ function Q(t) {
     kind: "records",
     id: t.id,
     label: t.label,
-    source: D(t),
+    source: k(t),
     fields: e,
     dateField: t.dateField ? s(t.dateField, "date") : void 0,
     timeGrain: t.timeGrain,
@@ -98,7 +98,7 @@ function Q(t) {
       field: s(t.orderBy.field),
       direction: t.orderBy.direction
     } : void 0,
-    inputs: k(t.inputs),
+    inputs: D(t.inputs),
     limit: t.limit
   };
 }
@@ -118,7 +118,7 @@ function J(t) {
     kind: "inputOptions",
     id: t.id,
     label: t.label,
-    source: D(t),
+    source: k(t),
     field: s(t.field, "dimension"),
     search: t.search,
     limit: t.limit
@@ -137,8 +137,8 @@ function H(t) {
     ...t.field ? { field: t.field } : {}
   };
 }
-function yt(t) {
-  const e = k(t);
+function gt(t) {
+  const e = D(t);
   return e.length > 0 ? e : void 0;
 }
 function W(t) {
@@ -181,7 +181,7 @@ function Z(t) {
     value: t.value
   };
 }
-function D(t) {
+function k(t) {
   return t.source;
 }
 function tt(t) {
@@ -194,7 +194,7 @@ function s(t, e) {
     role: t.role || e
   };
 }
-function k(t) {
+function D(t) {
   return (t || []).map(H);
 }
 function et(t) {
@@ -309,7 +309,7 @@ function dt(t) {
       idleData: S
     };
   } catch (r) {
-    const n = g(r);
+    const n = y(r);
     return {
       error: n,
       activeInputs: e,
@@ -335,7 +335,7 @@ function ct(t) {
       idleData: r
     };
   } catch (n) {
-    const o = g(n);
+    const o = y(n);
     return {
       error: o,
       activeInputs: e,
@@ -358,7 +358,7 @@ function ft(t) {
       idleData: I
     };
   } catch (e) {
-    const r = g(e);
+    const r = y(e);
     return {
       error: r,
       queryKey: d(void 0, void 0, r),
@@ -366,7 +366,7 @@ function ft(t) {
     };
   }
 }
-function g(t) {
+function y(t) {
   return t instanceof Error ? t : new Error(String(t));
 }
 function E(t) {
@@ -475,7 +475,7 @@ function At(t) {
     error: e.error || n.error
   };
 }
-function Dt(t) {
+function kt(t) {
   const e = m(() => ft(t), [t]), r = h(
     (a) => {
       var i;
@@ -513,7 +513,7 @@ function M(t, e, r, n) {
       u({
         status: "error",
         data: r,
-        error: g(f)
+        error: y(f)
       });
       return;
     }
@@ -532,7 +532,7 @@ function M(t, e, r, n) {
       l || u({
         status: "error",
         data: r,
-        error: g(f)
+        error: y(f)
       });
     }), () => {
       l = !0;
@@ -542,13 +542,13 @@ function M(t, e, r, n) {
 export {
   $ as SemaphorDataAppContext,
   vt as SemaphorDataAppProvider,
-  rt as createSemaphorDataAppExecutor,
+  rt as createSemaphorQueryExecutor,
   A as hasSemaphorInputValue,
   Y as normalizeSemaphorInputOptions,
   ut as readWindowRuntime,
   B as toSemaphorActiveInputSnapshots,
   H as toSemaphorInputBinding,
-  yt as toSemaphorInputBindings,
+  gt as toSemaphorInputBindings,
   J as toSemaphorInputOptionsIntent,
   W as toSemaphorInputSnapshots,
   X as toSemaphorInputSpec,
@@ -556,7 +556,7 @@ export {
   Q as toSemaphorRecordsIntent,
   st as useSemaphorDataAppRuntime,
   St as useSemaphorInput,
-  Dt as useSemaphorInputOptions,
+  kt as useSemaphorInputOptions,
   It as useSemaphorMetric,
   At as useSemaphorRecords
 };

package/dist/types/analytics-protocol.d.ts

@@ -309,7 +309,7 @@ export declare type SemaphorAnalyticsExecutionResult = {
     coverage?: {
         answeredObligations: string[];
         missingObligations: string[];
-        warnings: SemaphorAnalyticsValidationIssue[];
+        warnings?: SemaphorAnalyticsValidationIssue[];
     };
     missingFields?: string[];
     warnings?: string[];
@@ -652,11 +652,7 @@ export declare type SemaphorRecordsIntent = {
 
 export declare type SemaphorRecordsResult = SemaphorAnalyticsResultBase & {
     kind: 'records';
-    columns: Array<{
-        name: string;
-        label?: string;
-        dataType?: SemaphorFieldRef['dataType'];
-    }>;
+    columns: SemaphorResultColumn[];
     records: Array<Record<string, unknown>>;
 };
 
@@ -689,6 +685,26 @@ export declare type SemaphorRelationshipDiagnostics = {
 
 export declare type SemaphorRelationshipDiagnosticStatus = 'not_required' | 'resolved' | 'missing' | 'ambiguous' | 'fanout_risk' | 'unknown';
 
+export declare type SemaphorResultColumn = {
+    /**
+     * Stable row accessor for this result. Consumers should read values with
+     * `row[column.key]`; labels are display-only and may change.
+     */
+    key: string;
+    /**
+     * Semantic/source field name before result-key disambiguation.
+     */
+    name: string;
+    /**
+     * Human-facing display label.
+     */
+    label: string;
+    role?: SemaphorFieldRef['role'];
+    dataType?: SemaphorFieldRef['dataType'];
+    aggregate?: SemaphorFieldRef['aggregate'];
+    source?: SemaphorFieldRef['source'];
+};
+
 export declare type SemaphorSourceCoordinateInput = {
     databaseName?: string;
     schemaName?: string;

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

@@ -2,20 +2,29 @@ import { Context } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
-export declare function createSemaphorDataAppExecutor(): SemaphorDataAppExecutor;
+export declare function createSemaphorQueryExecutor(): SemaphorQueryExecutor;
 
 export declare function hasSemaphorInputValue(value: unknown): boolean;
 
 export declare function normalizeSemaphorInputOptions(options?: Array<{
     label: string;
-    value: SemaphorDataAppOptionValue;
-} | SemaphorDataAppOptionValue>): {
+    value: SemaphorOptionValue;
+} | SemaphorOptionValue>): {
     label: string;
-    value: SemaphorDataAppOptionValue;
+    value: SemaphorOptionValue;
 }[];
 
 export declare function readWindowRuntime(): SemaphorDataAppWindowRuntime | undefined;
 
+export declare type SemaphorActiveInput<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBinding & {
+    kind: 'filter' | 'control';
+    label?: string;
+    value?: TValue;
+    isActive: boolean;
+    operator?: SemaphorInputOperator;
+    controlRole?: SemaphorControlRole;
+};
+
 declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
 
 declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
@@ -43,108 +52,164 @@ declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
 
-export declare const SemaphorDataAppContext: Context<SemaphorDataAppRuntime>;
-
-export declare type SemaphorDataAppControlInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppInputBase<TValue> & {
+export declare type SemaphorControlInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
     kind: 'control';
-    role: SemaphorDataAppControlRole;
+    role: SemaphorControlRole;
 };
 
-export declare type SemaphorDataAppControlRole = 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+export declare type SemaphorControlRole = 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
 
-export declare type SemaphorDataAppExecutor = {
-    executeMetric(intent: SemaphorMetricIntent, context: SemaphorDataAppExecutorContext): Promise<SemaphorDataAppMetricData>;
-    executeRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(intent: SemaphorRecordsIntent, context: SemaphorDataAppExecutorContext): Promise<SemaphorDataAppRecordsData<TRecord>>;
-    executeInputOptions(intent: Extract<SemaphorAnalyticsIntent, {
-        kind: 'inputOptions';
-    }>, context: SemaphorDataAppExecutorContext): Promise<SemaphorDataAppInputOptionsData>;
+export declare const SemaphorDataAppContext: Context<SemaphorDataAppRuntime>;
+
+export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, children, }: SemaphorDataAppProviderProps): JSX.Element;
+
+export declare type SemaphorDataAppProviderProps = SemaphorQueryExecutorContext & {
+    executor?: SemaphorQueryExecutor;
+    children: ReactNode;
 };
 
-export declare type SemaphorDataAppExecutorContext = {
-    token?: string;
+export declare type SemaphorDataAppRuntime = SemaphorQueryExecutorContext & {
+    executor?: SemaphorQueryExecutor;
+};
+
+declare type SemaphorDataAppWindowRuntime = {
     apiBaseUrl?: string;
-    activeInputs?: SemaphorDataAppInputSnapshot[];
+    dataApiBaseUrl?: string;
+    authToken?: null | {
+        accessToken?: string;
+    };
 };
 
-export declare type SemaphorDataAppFieldSpec = SemaphorFieldRef;
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
-export declare type SemaphorDataAppFilterInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppInputBase<TValue> & {
+declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+export declare type SemaphorFilterInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
     kind: 'filter';
-    field: SemaphorDataAppFieldSpec;
+    field: SemaphorQueryField;
     operator?: SemaphorInputOperator;
     multi?: boolean;
 };
 
-declare type SemaphorDataAppInputBase<TValue extends SemaphorDataAppInputValue> = {
+declare type SemaphorInputBase<TValue extends SemaphorInputValue> = {
     id: string;
     label?: string;
     value?: TValue;
     defaultValue?: TValue;
     onValueChange?: (value: TValue | undefined) => void;
-    options?: Array<SemaphorDataAppInputOption | SemaphorDataAppOptionValue>;
+    options?: Array<SemaphorInputOption | SemaphorOptionValue>;
 };
 
-export declare type SemaphorDataAppInputHandle<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = {
+declare type SemaphorInputBinding = {
+    inputId: string;
+    field?: SemaphorFieldRef;
+};
+
+export declare type SemaphorInputHandle<TValue extends SemaphorInputValue = SemaphorInputValue> = {
     id: string;
     kind: 'filter' | 'control';
     label?: string;
     field?: SemaphorFieldRef;
     operator?: SemaphorInputOperator;
-    controlRole?: SemaphorDataAppControlRole;
+    controlRole?: SemaphorControlRole;
     value: TValue | undefined;
-    options: SemaphorDataAppInputOption[];
+    options: SemaphorInputOption[];
     isActive: boolean;
     setValue(value: TValue | undefined): void;
     clear(): void;
-    toAnalyticsInput(): SemaphorDataAppInputSnapshot<TValue>;
+    toAnalyticsInput(): SemaphorActiveInput<TValue>;
 };
 
-export declare type SemaphorDataAppInputOption = {
+declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
+
+export declare type SemaphorInputOption = {
     label: string;
-    value: SemaphorDataAppOptionValue;
+    value: SemaphorOptionValue;
     count?: number;
 };
 
-export declare type SemaphorDataAppInputOptionsData = {
-    options: SemaphorDataAppInputOption[];
+declare type SemaphorInputOptionsIntent = {
+    kind: 'inputOptions';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorSourceRef;
+    field: SemaphorFieldRef;
+    search?: string;
+    limit?: number;
 };
 
-export declare type SemaphorDataAppInputOptionsResult = SemaphorDataAppQueryState & SemaphorDataAppInputOptionsData & {
+export declare type SemaphorInputOptionsPayload = {
+    options: SemaphorInputOption[];
+};
+
+export declare type SemaphorInputOptionsQueryResult = SemaphorQueryState & SemaphorInputOptionsPayload & {
     id?: string;
     intent?: Extract<SemaphorAnalyticsIntent, {
         kind: 'inputOptions';
     }>;
 };
 
-export declare type SemaphorDataAppInputOptionsSpec = SemaphorDataAppSourceSpec & {
+export declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & {
     id?: string;
     label?: string;
-    field: SemaphorDataAppFieldSpec;
+    field: SemaphorQueryField;
     search?: string;
     limit?: number;
 };
 
-export declare type SemaphorDataAppInputReference = SemaphorInputBinding | SemaphorDataAppInputSnapshot | SemaphorDataAppInputHandle;
+export declare type SemaphorInputReference = SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle;
 
-export declare type SemaphorDataAppInputSnapshot<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorInputBinding & {
-    kind: 'filter' | 'control';
-    label?: string;
-    value?: TValue;
-    isActive: boolean;
-    operator?: SemaphorInputOperator;
-    controlRole?: SemaphorDataAppControlRole;
-};
+export declare type SemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorFilterInputSpec<TValue> | SemaphorControlInputSpec<TValue>;
 
-export declare type SemaphorDataAppInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppFilterInputSpec<TValue> | SemaphorDataAppControlInputSpec<TValue>;
+export declare type SemaphorInputValue = SemaphorScalar | SemaphorScalar[];
 
-export declare type SemaphorDataAppInputValue = SemaphorDataAppScalar | SemaphorDataAppScalar[];
+declare type SemaphorMetricAnalysis = {
+    kind: 'period_change';
+    orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
+    direction?: 'increase' | 'decrease' | 'both';
+    timeWindow?: SemaphorTimeWindow;
+};
 
-export declare type SemaphorDataAppMetricComparison = {
+export declare type SemaphorMetricComparison = {
     kind: 'previous_period' | 'previous_year' | 'target';
     targetValue?: number;
 };
 
-export declare type SemaphorDataAppMetricData = {
+declare type SemaphorMetricIntent = {
+    kind: 'metric';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    source: SemaphorSourceRef;
+    metrics: SemaphorFieldRef[];
+    primaryMetric?: SemaphorFieldRef;
+    label?: string;
+    dateField?: SemaphorFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    timeWindow?: SemaphorTimeWindow;
+    dimensions?: SemaphorFieldRef[];
+    filters?: SemaphorAnalyticsFilter[];
+    comparison?: {
+        kind: 'previous_period' | 'previous_year' | 'target';
+        targetValue?: number;
+    };
+    analysis?: SemaphorMetricAnalysis;
+    orderBy?: {
+        field: SemaphorFieldRef;
+        direction: 'asc' | 'desc';
+    };
+    inputs?: SemaphorInputBinding[];
+    limit?: number;
+};
+
+export declare type SemaphorMetricPayload = {
     value: number | string | null;
     metrics?: Record<string, number | string | null>;
     comparisonValue?: number | string | null;
@@ -153,168 +218,77 @@ export declare type SemaphorDataAppMetricData = {
     records?: Array<Record<string, unknown>>;
 };
 
-export declare type SemaphorDataAppMetricResult = SemaphorDataAppQueryState & SemaphorDataAppMetricData & {
+export declare type SemaphorMetricQueryResult = SemaphorQueryState & SemaphorMetricPayload & {
     id?: string;
     intent?: SemaphorMetricIntent;
 };
 
-export declare type SemaphorDataAppMetricSpec = SemaphorDataAppSourceSpec & {
+export declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & {
     id?: string;
     label?: string;
-    metrics: SemaphorDataAppNonEmptyArray<SemaphorDataAppFieldSpec>;
-    primaryMetric?: SemaphorDataAppFieldSpec;
-    dateField?: SemaphorDataAppFieldSpec;
+    metrics: SemaphorNonEmptyArray<SemaphorQueryField>;
+    primaryMetric?: SemaphorQueryField;
+    dateField?: SemaphorQueryField;
     timeGrain?: SemaphorTimeGrain;
-    dimensions?: SemaphorDataAppFieldSpec[];
-    comparison?: SemaphorDataAppMetricComparison;
-    orderBy?: SemaphorDataAppOrderBy;
-    inputs?: SemaphorDataAppInputReference[];
+    dimensions?: SemaphorQueryField[];
+    comparison?: SemaphorMetricComparison;
+    orderBy?: SemaphorQueryOrderBy;
+    inputs?: SemaphorInputReference[];
     limit?: number;
 };
 
-export declare type SemaphorDataAppNonEmptyArray<T> = [T, ...T[]];
-
-export declare type SemaphorDataAppOptionValue = string | number | boolean;
-
-export declare type SemaphorDataAppOrderBy = {
-    field: SemaphorDataAppFieldSpec;
-    direction: 'asc' | 'desc';
-};
-
-export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, children, }: SemaphorDataAppProviderProps): JSX.Element;
+export declare type SemaphorNonEmptyArray<T> = [T, ...T[]];
 
-export declare type SemaphorDataAppProviderProps = SemaphorDataAppExecutorContext & {
-    executor?: SemaphorDataAppExecutor;
-    children: ReactNode;
-};
+export declare type SemaphorOptionValue = string | number | boolean;
 
-export declare type SemaphorDataAppQueryState = {
-    status: SemaphorDataAppQueryStatus;
-    isLoading: boolean;
-    error: Error | null;
-};
-
-export declare type SemaphorDataAppQueryStatus = 'idle' | 'loading' | 'success' | 'error';
-
-declare type SemaphorDataAppRecordsBaseSpec = SemaphorDataAppSourceSpec & {
-    id?: string;
-    label?: string;
-    dateField?: SemaphorDataAppFieldSpec;
-    timeGrain?: SemaphorTimeGrain;
-    orderBy?: SemaphorDataAppRecordsOrderBy;
-    inputs?: SemaphorDataAppInputReference[];
-    limit?: number;
-};
-
-export declare type SemaphorDataAppRecordsData<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
-    records: TRecord[];
-    columns?: Array<{
-        name: string;
-        label?: string;
-        dataType?: SemaphorFieldRef['dataType'];
-        role?: SemaphorFieldRef['role'];
-    }>;
-    rowCount?: number;
-};
-
-export declare type SemaphorDataAppRecordsFieldSpec = SemaphorFieldRef & {
-    role: NonNullable<SemaphorFieldRef['role']>;
-};
-
-export declare type SemaphorDataAppRecordsOrderBy = SemaphorDataAppOrderBy;
-
-export declare type SemaphorDataAppRecordsResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorDataAppQueryState & SemaphorDataAppRecordsData<TRecord> & {
-    id?: string;
-    intent?: SemaphorRecordsIntent;
-};
-
-declare type SemaphorDataAppRecordsSelectorSpec = {
-    fields: SemaphorDataAppNonEmptyArray<SemaphorDataAppRecordsFieldSpec>;
-};
-
-export declare type SemaphorDataAppRecordsSpec = SemaphorDataAppRecordsBaseSpec & SemaphorDataAppRecordsSelectorSpec;
-
-export declare type SemaphorDataAppRuntime = SemaphorDataAppExecutorContext & {
-    executor?: SemaphorDataAppExecutor;
-};
-
-export declare type SemaphorDataAppScalar = string | number | boolean | null;
+declare type SemaphorProtocolVersion = 1;
 
-export declare type SemaphorDataAppSourceSpec = {
-    source: SemaphorSourceRef;
+export declare type SemaphorQueryExecutor = {
+    executeMetric(intent: SemaphorMetricIntent, context: SemaphorQueryExecutorContext): Promise<SemaphorMetricPayload>;
+    executeRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(intent: SemaphorRecordsIntent, context: SemaphorQueryExecutorContext): Promise<SemaphorRecordsPayload<TRecord>>;
+    executeInputOptions(intent: Extract<SemaphorAnalyticsIntent, {
+        kind: 'inputOptions';
+    }>, context: SemaphorQueryExecutorContext): Promise<SemaphorInputOptionsPayload>;
 };
 
-declare type SemaphorDataAppWindowRuntime = {
+export declare type SemaphorQueryExecutorContext = {
+    token?: string;
     apiBaseUrl?: string;
-    dataApiBaseUrl?: string;
-    authToken?: null | {
-        accessToken?: string;
-    };
+    activeInputs?: SemaphorActiveInput[];
 };
 
-declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
-
-declare type SemaphorFieldRef = {
-    name: string;
-    label?: string;
-    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
-    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
-    source?: SemaphorSourceRef;
-    aggregate?: SemaphorAggregateFunction;
-};
+export declare type SemaphorQueryField = SemaphorFieldRef;
 
-declare type SemaphorInputBinding = {
-    inputId: string;
-    field?: SemaphorFieldRef;
+export declare type SemaphorQueryOrderBy = {
+    field: SemaphorQueryField;
+    direction: 'asc' | 'desc';
 };
 
-declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
-
-declare type SemaphorInputOptionsIntent = {
-    kind: 'inputOptions';
-    version?: SemaphorProtocolVersion;
-    id?: string;
-    label?: string;
+export declare type SemaphorQuerySourceSpec = {
     source: SemaphorSourceRef;
-    field: SemaphorFieldRef;
-    search?: string;
-    limit?: number;
 };
 
-declare type SemaphorMetricAnalysis = {
-    kind: 'period_change';
-    orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
-    direction?: 'increase' | 'decrease' | 'both';
-    timeWindow?: SemaphorTimeWindow;
+export declare type SemaphorQueryState = {
+    status: SemaphorQueryStatus;
+    isLoading: boolean;
+    error: Error | null;
 };
 
-declare type SemaphorMetricIntent = {
-    kind: 'metric';
-    version?: SemaphorProtocolVersion;
+export declare type SemaphorQueryStatus = 'idle' | 'loading' | 'success' | 'error';
+
+declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & {
     id?: string;
-    source: SemaphorSourceRef;
-    metrics: SemaphorFieldRef[];
-    primaryMetric?: SemaphorFieldRef;
     label?: string;
-    dateField?: SemaphorFieldRef;
+    dateField?: SemaphorQueryField;
     timeGrain?: SemaphorTimeGrain;
-    timeWindow?: SemaphorTimeWindow;
-    dimensions?: SemaphorFieldRef[];
-    filters?: SemaphorAnalyticsFilter[];
-    comparison?: {
-        kind: 'previous_period' | 'previous_year' | 'target';
-        targetValue?: number;
-    };
-    analysis?: SemaphorMetricAnalysis;
-    orderBy?: {
-        field: SemaphorFieldRef;
-        direction: 'asc' | 'desc';
-    };
-    inputs?: SemaphorInputBinding[];
+    orderBy?: SemaphorRecordsOrderBy;
+    inputs?: SemaphorInputReference[];
     limit?: number;
 };
 
-declare type SemaphorProtocolVersion = 1;
+export declare type SemaphorRecordsField = SemaphorFieldRef & {
+    role: NonNullable<SemaphorFieldRef['role']>;
+};
 
 declare type SemaphorRecordsIntent = {
     kind: 'records';
@@ -333,6 +307,47 @@ declare type SemaphorRecordsIntent = {
     inputs?: SemaphorInputBinding[];
 };
 
+export declare type SemaphorRecordsOrderBy = SemaphorQueryOrderBy;
+
+export declare type SemaphorRecordsPayload<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
+    records: TRecord[];
+    columns?: SemaphorResultColumn[];
+    rowCount?: number;
+};
+
+export declare type SemaphorRecordsQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryState & SemaphorRecordsPayload<TRecord> & {
+    id?: string;
+    intent?: SemaphorRecordsIntent;
+};
+
+export declare type SemaphorRecordsQuerySpec = SemaphorRecordsBaseQuerySpec & SemaphorRecordsSelectorSpec;
+
+declare type SemaphorRecordsSelectorSpec = {
+    fields: SemaphorNonEmptyArray<SemaphorRecordsField>;
+};
+
+export declare type SemaphorResultColumn = {
+    /**
+     * Stable row accessor for this result. Consumers should read values with
+     * `row[column.key]`; labels are display-only and may change.
+     */
+    key: string;
+    /**
+     * Semantic/source field name before result-key disambiguation.
+     */
+    name: string;
+    /**
+     * Human-facing display label.
+     */
+    label: string;
+    role?: SemaphorFieldRef['role'];
+    dataType?: SemaphorFieldRef['dataType'];
+    aggregate?: SemaphorFieldRef['aggregate'];
+    source?: SemaphorFieldRef['source'];
+};
+
+export declare type SemaphorScalar = string | number | boolean | null;
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -382,37 +397,37 @@ declare type SemaphorTimeWindow = {
     completeness?: 'include_partial' | 'complete_periods';
 };
 
-export declare function toSemaphorActiveInputSnapshots(inputs: SemaphorDataAppInputReference[] | undefined): SemaphorDataAppInputSnapshot[];
+export declare function toSemaphorActiveInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
 
-export declare function toSemaphorInputBinding(input: SemaphorDataAppInputReference): SemaphorInputBinding;
+export declare function toSemaphorInputBinding(input: SemaphorInputReference): SemaphorInputBinding;
 
-export declare function toSemaphorInputBindings(inputs: SemaphorDataAppInputReference[] | undefined): SemaphorInputBinding[] | undefined;
+export declare function toSemaphorInputBindings(inputs: SemaphorInputReference[] | undefined): SemaphorInputBinding[] | undefined;
 
-export declare function toSemaphorInputOptionsIntent(spec: SemaphorDataAppInputOptionsSpec): Extract<SemaphorAnalyticsIntent, {
+export declare function toSemaphorInputOptionsIntent(spec: SemaphorInputOptionsQuerySpec): Extract<SemaphorAnalyticsIntent, {
     kind: 'inputOptions';
 }>;
 
-export declare function toSemaphorInputSnapshots(inputs: SemaphorDataAppInputReference[] | undefined): SemaphorDataAppInputSnapshot[];
+export declare function toSemaphorInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
 
-export declare function toSemaphorInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue>(spec: SemaphorDataAppInputSpec<TValue>): SemaphorInputBinding & {
-    kind: SemaphorDataAppInputSpec['kind'];
+export declare function toSemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputBinding & {
+    kind: SemaphorInputSpec['kind'];
     label?: string;
     field?: SemaphorFieldRef;
     operator?: SemaphorInputOperator;
 };
 
-export declare function toSemaphorMetricIntent(spec: SemaphorDataAppMetricSpec): SemaphorMetricIntent;
+export declare function toSemaphorMetricIntent(spec: SemaphorMetricQuerySpec): SemaphorMetricIntent;
 
-export declare function toSemaphorRecordsIntent(spec: SemaphorDataAppRecordsSpec): SemaphorRecordsIntent;
+export declare function toSemaphorRecordsIntent(spec: SemaphorRecordsQuerySpec): SemaphorRecordsIntent;
 
 export declare function useSemaphorDataAppRuntime(): SemaphorDataAppRuntime;
 
-export declare function useSemaphorInput<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue>(spec: SemaphorDataAppInputSpec<TValue>): SemaphorDataAppInputHandle;
+export declare function useSemaphorInput<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputHandle;
 
-export declare function useSemaphorInputOptions(spec: SemaphorDataAppInputOptionsSpec): SemaphorDataAppInputOptionsResult;
+export declare function useSemaphorInputOptions(spec: SemaphorInputOptionsQuerySpec): SemaphorInputOptionsQueryResult;
 
-export declare function useSemaphorMetric(spec: SemaphorDataAppMetricSpec): SemaphorDataAppMetricResult;
+export declare function useSemaphorMetric(spec: SemaphorMetricQuerySpec): SemaphorMetricQueryResult;
 
-export declare function useSemaphorRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(spec: SemaphorDataAppRecordsSpec): SemaphorDataAppRecordsResult<TRecord>;
+export declare function useSemaphorRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(spec: SemaphorRecordsQuerySpec): SemaphorRecordsQueryResult<TRecord>;
 
 export { }

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.345",
+  "version": "0.1.346",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",