@segmentstream-cloud/app 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,9 @@
 # @segmentstream-cloud/app
 
-Sign-in and sessions for SegmentStream workspace apps built with Next.js (App Router,
-version 16 or later). Every visitor signs in with their SegmentStream account, and only
-members of the app's workspace get in.
+Sign-in, sessions, and warehouse data access for SegmentStream workspace apps built with
+Next.js (App Router, version 16 or later). Every visitor signs in with their SegmentStream
+account, only members of the app's workspace get in, and the app reads workspace data as
+that user without holding any warehouse credentials.
 
 ## Install
 
@@ -77,6 +78,77 @@ To sign out, post a form to the SDK route:
 </form>
 ```
 
+## Query the warehouse
+
+```tsx
+import { sql } from "@segmentstream-cloud/app";
+import { segmentstream } from "@/segmentstream";
+
+type Revenue = { order_date: string; total_revenue: number };
+
+export default async function Page() {
+  const { rows } = await segmentstream.warehouse.query<Revenue>(
+    `SELECT order_date, total_revenue
+     FROM gold.revenue_summary
+     WHERE order_date >= @from
+     ORDER BY order_date`,
+    { params: { from: sql.date("2026-09-01") } },
+  );
+
+  return <pre>{JSON.stringify(rows, null, 2)}</pre>;
+}
+```
+
+- Queries are read-only GoogleSQL over the workspace warehouse. `dataset.table` resolves
+  to the workspace's project. Anything other than a single `SELECT` is rejected.
+- Pass values as named `@parameters` in `params`; never build SQL from user input.
+  Strings, booleans, `bigint`, safe integers (`INT64`), other numbers (`FLOAT64`), `Date`
+  (`TIMESTAMP`) and arrays of these are typed automatically. Use `sql.date()`,
+  `sql.datetime()`, `sql.timestamp()`, `sql.numeric()`, `sql.bignumeric()`, `sql.int64()`
+  and `sql.array(type, values)` for anything else.
+- `query()` waits for running queries (`timeoutMs`, default 60 s) and follows result
+  pages up to `maxRows` (default 10,000); `truncated` reports whether more rows exist.
+  `maximumBytesBilled` lowers the per-query byte ceiling; `warehouse.dryRun()` returns the
+  estimated bytes and result columns without running the query.
+- Long queries keep running in the warehouse for up to an hour after `query()` stops
+  waiting. It then throws `query_timeout` with a `queryId`. Resume the query from a later
+  request, for example a Route Handler your page polls, with
+  `warehouse.result(queryId)`. Each request carries a fresh session token, so a query can
+  outlive the 5-minute token. Don't hold one request open for minutes.
+- Values arrive as JSON: safe integers as numbers, larger integers and decimals as strings,
+  timestamps as ISO strings, records and arrays as JSON strings.
+
+Semantic models give governed metrics without SQL:
+
+```ts
+const { rows } = await segmentstream.semantic.query("advertising", {
+  dimensions: ["platform"],
+  measures: ["spend", "clicks"],
+  dateRange: { from: "2026-09-01", to: "2026-09-30" },
+  filters: [{ dimension: "currency", operator: "equals", value: "USD" }],
+});
+```
+
+`semantic.list()` and `semantic.get(name)` describe the deployed models.
+
+## Call the SegmentStream API
+
+The session token works on the whole SegmentStream API, with the signed-in member's
+organization role and permissions, exactly like their own login. `fetch` adds it to any
+API path:
+
+```ts
+const response = await segmentstream.fetch(
+  `/api/v1/workspaces/${user.workspaceId}/warehouse/datasets`,
+);
+```
+
+`warehouse` and `semantic` are typed helpers over the same API, for the app's own
+workspace. Every call is server-only: use it from Server Components, Route Handlers, and
+Server Functions behind the proxy, and pass results to Client Components as props or
+through your own Route Handlers. Typed helpers throw `SegmentStreamApiError` with the API
+error `code`, `status`, `detail` and, for timeouts, the `queryId`.
+
 ## How requests are handled
 
 - Page navigations without a session are redirected to SegmentStream to sign in, then
@@ -102,11 +174,17 @@ and the SDK drops the `__Host-` prefix and `Secure` attribute only for `http://l
 - The app never sees SegmentStream's identity-provider tokens. It receives a short-lived
   (5-minute) ES256 session token scoped to this workspace app and a rotating refresh
   token, both in `HttpOnly`, `SameSite=Lax` cookies (`__Host-` and `Secure` in production).
-- Session tokens are verified locally against SegmentStream's published keys: issuer,
-  expiry, workspace, organization, and an `app:` audience.
+- Session tokens are verified against SegmentStream's published keys: issuer, expiry,
+  workspace, organization, and an `app:` audience.
 - The proxy refreshes expired sessions silently. When access is revoked, the next refresh
   fails and the user is signed out.
 - Sign-in uses the authorization-code flow with PKCE (S256) and a single-use `state`.
+- API calls carry the session token, which SegmentStream accepts as the member: their
+  WorkOS role and permissions, read at sign-in and every refresh, decide what the call may
+  do. App code therefore acts as whoever is visiting, across their organization, so treat
+  deploying app code like any other code your organization runs with member access.
+  Warehouse queries run with the workspace's own identity; the app never holds warehouse
+  credentials.
 
 ## License
 

package/dist/app.d.ts

@@ -1,3 +1,4 @@
+import type { SemanticClient, WarehouseClient } from "./data.js";
 import type { SegmentStreamAppConfig } from "./config.js";
 import type { SegmentStreamRouteHandlers } from "./handlers.js";
 import type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
@@ -14,6 +15,15 @@ export interface SegmentStreamApp {
     readonly requireUser: () => Promise<AppUser>;
     /** The verified app session token for this request, or `null`. */
     readonly getAccessToken: () => Promise<string | null>;
+    /**
+     * Calls any SegmentStream API path as the signed-in member, with their organization role
+     * and permissions. Server-only; the session token never reaches the browser.
+     */
+    readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    /** Read-only SQL over the workspace warehouse, as the signed-in member. Server-only. */
+    readonly warehouse: WarehouseClient;
+    /** Governed metrics from the workspace's deployed semantic models. Server-only. */
+    readonly semantic: SemanticClient;
 }
 /** Replaceable capabilities, for tests. */
 export interface AppDependencies {

package/dist/app.js

@@ -1,4 +1,5 @@
 import { resolveConfig } from "./config.js";
+import { createDataClient } from "./data.js";
 import { createHandlers } from "./handlers.js";
 import { createProxy } from "./proxy.js";
 import { createServerSession } from "./server.js";
@@ -16,11 +17,19 @@ export function createApp(config, dependencies = {}) {
         revokeSession: sessionClient.revoke,
     };
     const serverSession = createServerSession(context);
+    const data = createDataClient({
+        config: resolved,
+        fetch: fetchImplementation,
+        getAccessToken: serverSession.getAccessToken,
+    });
     return {
         proxy: (options) => createProxy(context, options),
         handlers: () => createHandlers(context),
         getUser: serverSession.getUser,
         requireUser: serverSession.requireUser,
         getAccessToken: serverSession.getAccessToken,
+        fetch: data.fetch,
+        warehouse: data.warehouse,
+        semantic: data.semantic,
     };
 }

package/dist/data.d.ts

@@ -0,0 +1,138 @@
+import type { ResolvedConfig } from "./config.js";
+import type { QueryParameters } from "./parameters.js";
+import type { Fetch } from "./sessions.js";
+/** A failed SegmentStream API request; `code` is the API error code. */
+export declare class SegmentStreamApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly detail: string;
+    readonly requestId: string | undefined;
+    readonly retryable: boolean;
+    /** The warehouse query this error concerns, when one was started. */
+    readonly queryId: string | undefined;
+    constructor(input: {
+        readonly code: string;
+        readonly status: number;
+        readonly detail: string;
+        readonly requestId?: string | undefined;
+        readonly retryable?: boolean;
+        readonly queryId?: string | undefined;
+    });
+}
+export type WarehouseValue = string | number | boolean | null;
+export type WarehouseRow = Record<string, WarehouseValue>;
+export interface WarehouseColumn {
+    readonly name: string;
+    readonly type: string;
+    readonly mode: string;
+    readonly description: string;
+}
+/** How much of a query result to wait for and collect. */
+export interface WarehouseReadOptions {
+    /** Rows to collect across pages before stopping. Defaults to 10,000. */
+    readonly maxRows?: number;
+    /** Rows per API page, 1–1,000. Defaults to the smaller of `maxRows` and 1,000. */
+    readonly pageSize?: number;
+    /** How long to wait for a running query. Defaults to 60 seconds. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface WarehouseQueryOptions extends WarehouseReadOptions {
+    /** Values for named `@parameters` in the SQL. Never interpolate values into the SQL text. */
+    readonly params?: QueryParameters;
+    /** Lowers the workspace's per-query byte ceiling for this query. */
+    readonly maximumBytesBilled?: number | bigint | string;
+}
+export interface WarehouseQueryResult<Row = WarehouseRow> {
+    readonly queryId: string | null;
+    readonly columns: readonly WarehouseColumn[];
+    readonly rows: Row[];
+    /** Rows in the full result, which may exceed `rows` when `truncated`. */
+    readonly totalRows: number | null;
+    /** True when more rows exist than `maxRows` allowed. */
+    readonly truncated: boolean;
+    readonly bytesProcessed: string | null;
+    readonly bytesBilled: string | null;
+    readonly cacheHit: boolean | null;
+}
+export interface WarehouseDryRun {
+    readonly columns: readonly WarehouseColumn[];
+    readonly bytesProcessed: string | null;
+    readonly maximumBytesBilled: string;
+}
+export interface SemanticQueryRequest {
+    readonly dimensions: readonly string[];
+    readonly measures: readonly string[];
+    readonly dateRange: {
+        readonly from: string;
+        readonly to: string;
+    };
+    readonly granularity?: "day" | "week" | "month";
+    readonly filters?: ReadonlyArray<{
+        readonly dimension: string;
+        readonly operator: "equals" | "in" | "isNull" | "isNotNull";
+        readonly value?: string | number | boolean;
+        readonly values?: ReadonlyArray<string | number | boolean>;
+    }>;
+    readonly orderBy?: ReadonlyArray<{
+        readonly measure?: string;
+        readonly dimension?: string;
+        readonly direction: "asc" | "desc";
+    }>;
+    readonly limit?: number;
+}
+export interface SemanticField {
+    readonly name: string;
+    readonly label: string;
+    readonly type: string;
+    readonly unit?: string;
+    readonly format?: string;
+}
+export interface SemanticQueryResult<Row = Record<string, string | boolean | null>> {
+    readonly deploymentId: string | null;
+    readonly definitionDigest: string;
+    readonly fields: readonly SemanticField[];
+    readonly rows: Row[];
+    readonly truncated: boolean;
+    readonly execution: {
+        readonly elapsedMs: number;
+        readonly bytesProcessed?: string;
+        readonly bytesBilled?: string;
+    };
+}
+export interface WarehouseClient {
+    /** Runs read-only SQL in the workspace warehouse as the signed-in user's app session. */
+    readonly query: <Row = WarehouseRow>(sql: string, options?: WarehouseQueryOptions) => Promise<WarehouseQueryResult<Row>>;
+    /**
+     * Resumes a query by ID from a later request. Queries keep running in the warehouse for
+     * up to an hour after `query()` stops waiting, and each request uses a fresh app token.
+     */
+    readonly result: <Row = WarehouseRow>(queryId: string, options?: WarehouseReadOptions) => Promise<WarehouseQueryResult<Row>>;
+    /** Validates SQL and estimates bytes processed without running it. */
+    readonly dryRun: (sql: string, options?: Pick<WarehouseQueryOptions, "params" | "maximumBytesBilled" | "signal">) => Promise<WarehouseDryRun>;
+}
+export interface SemanticClient {
+    readonly list: () => Promise<{
+        readonly deploymentId: string | null;
+        readonly models: readonly unknown[];
+    }>;
+    readonly get: (model: string) => Promise<{
+        readonly deploymentId: string | null;
+        readonly definitionDigest: string;
+        readonly model: unknown;
+    }>;
+    readonly query: <Row = Record<string, string | boolean | null>>(model: string, request: SemanticQueryRequest) => Promise<SemanticQueryResult<Row>>;
+}
+export interface DataClientDependencies {
+    readonly config: ResolvedConfig;
+    readonly fetch: Fetch;
+    readonly getAccessToken: () => Promise<string | null>;
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    readonly now?: () => number;
+}
+/** Server-side SegmentStream API access as the signed-in member. */
+export declare function createDataClient(dependencies: DataClientDependencies): {
+    fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    warehouse: WarehouseClient;
+    semantic: SemanticClient;
+};

package/dist/data.js

@@ -0,0 +1,225 @@
+import { encodeParameters } from "./parameters.js";
+/** A failed SegmentStream API request; `code` is the API error code. */
+export class SegmentStreamApiError extends Error {
+    code;
+    status;
+    detail;
+    requestId;
+    retryable;
+    /** The warehouse query this error concerns, when one was started. */
+    queryId;
+    constructor(input) {
+        super(`${input.detail} (${input.code})`);
+        this.name = "SegmentStreamApiError";
+        this.code = input.code;
+        this.status = input.status;
+        this.detail = input.detail;
+        this.requestId = input.requestId;
+        this.retryable = input.retryable ?? false;
+        this.queryId = input.queryId;
+    }
+}
+const REQUEST_TIMEOUT_MS = 45_000;
+const DEFAULT_MAX_ROWS = 10_000;
+const MAXIMUM_PAGE_SIZE = 1000;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const FIRST_POLL_MS = 500;
+const LONGEST_POLL_MS = 2000;
+/** Server-side SegmentStream API access as the signed-in member. */
+export function createDataClient(dependencies) {
+    const { config } = dependencies;
+    const workspace = `/api/v1/workspaces/${encodeURIComponent(config.workspaceId)}`;
+    const sleep = dependencies.sleep ?? defaultSleep;
+    const now = dependencies.now ?? Date.now;
+    /** Calls any SegmentStream API path as the signed-in member; the token never leaves the server. */
+    async function apiFetch(path, init = {}) {
+        if (!path.startsWith("/api/")) {
+            throw new TypeError('SegmentStream API paths start with "/api/", for example "/api/v1/me".');
+        }
+        const token = await dependencies.getAccessToken();
+        if (token === null) {
+            throw new SegmentStreamApiError({
+                code: "app_session_missing",
+                status: 401,
+                detail: "No signed-in SegmentStream session for this request; call SegmentStream from Server Components, Route Handlers, or Server Functions behind the SegmentStream proxy.",
+            });
+        }
+        const headers = new Headers(init.headers);
+        const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+        headers.set("authorization", `Bearer ${token}`);
+        if (!headers.has("accept")) {
+            headers.set("accept", "application/json");
+        }
+        try {
+            return await dependencies.fetch(`${config.baseUrl}${path}`, {
+                ...init,
+                headers,
+                cache: "no-store",
+                redirect: "error",
+                signal: init.signal ? AbortSignal.any([init.signal, timeout]) : timeout,
+            });
+        }
+        catch (error) {
+            if (init.signal?.aborted) {
+                throw error;
+            }
+            throw new SegmentStreamApiError({
+                code: "segmentstream_unreachable",
+                status: 503,
+                detail: "SegmentStream could not be reached.",
+                retryable: true,
+            });
+        }
+    }
+    async function call(method, path, body, signal) {
+        const response = await apiFetch(path, {
+            method,
+            ...(body === undefined
+                ? {}
+                : { body: JSON.stringify(body), headers: { "content-type": "application/json" } }),
+            ...(signal ? { signal } : {}),
+        });
+        const payload = await readJson(response);
+        if (!response.ok) {
+            throw errorFrom(response.status, payload);
+        }
+        return payload;
+    }
+    function limits(options) {
+        const maxRows = positiveInteger(options.maxRows ?? DEFAULT_MAX_ROWS, "maxRows");
+        const pageSize = positiveInteger(options.pageSize ?? Math.min(maxRows, MAXIMUM_PAGE_SIZE), "pageSize");
+        return { maxRows, pageSize, deadline: now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS) };
+    }
+    /** Waits for a running query, then follows pages up to `maxRows`. */
+    async function collect(first, { maxRows, pageSize, deadline }, signal) {
+        let page = first;
+        const queryId = page.id ?? null;
+        let wait = FIRST_POLL_MS;
+        while (page.state === "running") {
+            if (queryId === null || now() + wait > deadline) {
+                throw new SegmentStreamApiError({
+                    code: "query_timeout",
+                    status: 504,
+                    detail: "The query is still running; resume it from a later request with warehouse.result(queryId).",
+                    retryable: true,
+                    queryId: queryId ?? undefined,
+                });
+            }
+            await sleep(wait, signal);
+            wait = Math.min(wait * 2, LONGEST_POLL_MS);
+            page = (await read(queryId, pageSize, undefined, signal)).query;
+        }
+        const head = page;
+        const rows = [...page.rows];
+        while (page.nextPageToken !== undefined && rows.length < maxRows && queryId !== null) {
+            page = (await read(queryId, pageSize, page.nextPageToken, signal)).query;
+            rows.push(...page.rows);
+        }
+        return {
+            queryId,
+            columns: head.columns,
+            rows: rows.slice(0, maxRows),
+            totalRows: head.totalRows === undefined ? null : Number(head.totalRows),
+            truncated: rows.length > maxRows || page.nextPageToken !== undefined,
+            bytesProcessed: head.bytesProcessed ?? null,
+            bytesBilled: head.bytesBilled ?? null,
+            cacheHit: head.cacheHit ?? null,
+        };
+    }
+    async function query(sql, options = {}) {
+        const bounds = limits(options);
+        const { query: page } = await call("POST", `${workspace}/warehouse/queries`, {
+            sql,
+            parameters: encodeParameters(options.params),
+            ...bytesLimit(options.maximumBytesBilled),
+            pageSize: bounds.pageSize,
+        }, options.signal);
+        return collect(page, bounds, options.signal);
+    }
+    async function result(queryId, options = {}) {
+        const bounds = limits(options);
+        const { query: page } = await read(queryId, bounds.pageSize, undefined, options.signal);
+        return collect(page, bounds, options.signal);
+    }
+    function read(queryId, pageSize, pageToken, signal) {
+        const search = new URLSearchParams({ pageSize: String(pageSize) });
+        if (pageToken !== undefined) {
+            search.set("pageToken", pageToken);
+        }
+        return call("GET", `${workspace}/warehouse/queries/${encodeURIComponent(queryId)}?${search.toString()}`, undefined, signal);
+    }
+    const warehouse = {
+        query,
+        result,
+        dryRun: async (sql, options = {}) => {
+            const { query: page } = await call("POST", `${workspace}/warehouse/queries`, {
+                sql,
+                parameters: encodeParameters(options.params),
+                ...bytesLimit(options.maximumBytesBilled),
+                dryRun: true,
+            }, options.signal);
+            return {
+                columns: page.columns,
+                bytesProcessed: page.bytesProcessed ?? null,
+                maximumBytesBilled: page.maximumBytesBilled,
+            };
+        },
+    };
+    const semantic = {
+        list: () => call("GET", `${workspace}/semantic-models`),
+        get: (model) => call("GET", `${workspace}/semantic-models/${encodeURIComponent(model)}`),
+        query: (model, request) => call("POST", `${workspace}/semantic-models/${encodeURIComponent(model)}/query`, request),
+    };
+    return { fetch: apiFetch, warehouse, semantic };
+}
+function bytesLimit(value) {
+    if (value === undefined) {
+        return {};
+    }
+    const text = String(value);
+    if (!/^[1-9][0-9]*$/.test(text)) {
+        throw new TypeError("maximumBytesBilled must be a positive whole number of bytes.");
+    }
+    return { maximumBytesBilled: text };
+}
+function positiveInteger(value, name) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new TypeError(`${name} must be a positive integer.`);
+    }
+    return value;
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+function errorFrom(status, payload) {
+    const body = typeof payload === "object" && payload !== null ? payload : {};
+    return new SegmentStreamApiError({
+        code: typeof body.error === "string" ? body.error : `http_${status}`,
+        status,
+        detail: typeof body.detail === "string" ? body.detail : "SegmentStream rejected the request.",
+        requestId: typeof body.requestId === "string" ? body.requestId : undefined,
+        retryable: typeof body.retryable === "boolean" ? body.retryable : status >= 500,
+    });
+}
+function defaultSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}

package/dist/index.d.ts

@@ -11,7 +11,11 @@ import type { SegmentStreamAppConfig } from "./config.js";
  * ```
  */
 export declare function createSegmentStreamApp(config: SegmentStreamAppConfig): SegmentStreamApp;
+export { SegmentStreamApiError } from "./data.js";
+export { sql } from "./parameters.js";
 export type { SegmentStreamApp } from "./app.js";
+export type { SemanticClient, SemanticField, SemanticQueryRequest, SemanticQueryResult, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
+export type { ParameterType, QueryParameterValue, QueryParameters, TypedParameter, } from "./parameters.js";
 export type { SegmentStreamAppConfig } from "./config.js";
 export type { SegmentStreamRouteHandlers, RouteHandler } from "./handlers.js";
 export type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";

package/dist/index.js

@@ -12,3 +12,5 @@ import { createApp } from "./app.js";
 export function createSegmentStreamApp(config) {
     return createApp(config);
 }
+export { SegmentStreamApiError } from "./data.js";
+export { sql } from "./parameters.js";

package/dist/parameters.d.ts

@@ -0,0 +1,55 @@
+export declare const PARAMETER_TYPES: readonly ["STRING", "INT64", "FLOAT64", "NUMERIC", "BIGNUMERIC", "BOOL", "DATE", "DATETIME", "TIMESTAMP"];
+export type ParameterType = (typeof PARAMETER_TYPES)[number];
+declare const TYPED: unique symbol;
+/** A value with an explicit warehouse type, created with the `sql` helpers. */
+export interface TypedParameter {
+    readonly [TYPED]: true;
+    readonly type: ParameterType;
+    readonly value?: string;
+    readonly values?: readonly string[];
+}
+/** A value bound to a named `@parameter`; never spliced into the SQL text. */
+export type QueryParameterValue = string | number | bigint | boolean | Date | TypedParameter | ReadonlyArray<string | number | bigint | boolean | Date>;
+export type QueryParameters = Readonly<Record<string, QueryParameterValue>>;
+/** The wire form the SegmentStream API accepts. */
+export type EncodedParameter = {
+    readonly name: string;
+    readonly type: ParameterType;
+    readonly value: string;
+} | {
+    readonly name: string;
+    readonly type: ParameterType;
+    readonly values: readonly string[];
+};
+/**
+ * Explicit parameter types for values JavaScript cannot express unambiguously.
+ *
+ * ```ts
+ * await segmentstream.warehouse.query(
+ *   "SELECT * FROM gold.orders WHERE order_date >= @from AND amount > @minimum",
+ *   { params: { from: sql.date("2026-09-01"), minimum: sql.numeric("10.50") } },
+ * );
+ * ```
+ */
+export declare const sql: {
+    readonly string: (value: string) => TypedParameter;
+    readonly int64: (value: number | bigint | string) => TypedParameter;
+    readonly float64: (value: number) => TypedParameter;
+    readonly numeric: (value: string | number) => TypedParameter;
+    readonly bignumeric: (value: string | number) => TypedParameter;
+    readonly bool: (value: boolean) => TypedParameter;
+    /** A calendar date, `YYYY-MM-DD`; a `Date` uses its UTC day. */
+    readonly date: (value: string | Date) => TypedParameter;
+    /** A civil date and time without a time zone, `YYYY-MM-DDTHH:MM:SS[.ffffff]`. */
+    readonly datetime: (value: string) => TypedParameter;
+    readonly timestamp: (value: string | Date) => TypedParameter;
+    /** An array of one element type; needed for empty arrays and non-default element types. */
+    readonly array: (type: ParameterType, values: ReadonlyArray<string | number | bigint | boolean | Date>) => {
+        [TYPED]: true;
+        type: "STRING" | "INT64" | "FLOAT64" | "NUMERIC" | "BIGNUMERIC" | "BOOL" | "DATE" | "DATETIME" | "TIMESTAMP";
+        values: string[];
+    };
+};
+/** Infers warehouse types for named parameters and validates their names. */
+export declare function encodeParameters(parameters: QueryParameters | undefined): EncodedParameter[];
+export {};

package/dist/parameters.js

@@ -0,0 +1,118 @@
+export const PARAMETER_TYPES = [
+    "STRING",
+    "INT64",
+    "FLOAT64",
+    "NUMERIC",
+    "BIGNUMERIC",
+    "BOOL",
+    "DATE",
+    "DATETIME",
+    "TIMESTAMP",
+];
+const TYPED = Symbol.for("segmentstream.app.queryParameter");
+const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+function typed(type, value) {
+    return { [TYPED]: true, type, value };
+}
+function isoDate(value, name) {
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError(`sql.${name}() received an invalid Date.`);
+        }
+        return value.toISOString().slice(0, 10);
+    }
+    return value;
+}
+function timestamp(value) {
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError("sql.timestamp() received an invalid Date.");
+        }
+        return value.toISOString();
+    }
+    return value;
+}
+/**
+ * Explicit parameter types for values JavaScript cannot express unambiguously.
+ *
+ * ```ts
+ * await segmentstream.warehouse.query(
+ *   "SELECT * FROM gold.orders WHERE order_date >= @from AND amount > @minimum",
+ *   { params: { from: sql.date("2026-09-01"), minimum: sql.numeric("10.50") } },
+ * );
+ * ```
+ */
+export const sql = {
+    string: (value) => typed("STRING", value),
+    int64: (value) => typed("INT64", String(value)),
+    float64: (value) => typed("FLOAT64", String(value)),
+    numeric: (value) => typed("NUMERIC", String(value)),
+    bignumeric: (value) => typed("BIGNUMERIC", String(value)),
+    bool: (value) => typed("BOOL", String(value)),
+    /** A calendar date, `YYYY-MM-DD`; a `Date` uses its UTC day. */
+    date: (value) => typed("DATE", isoDate(value, "date")),
+    /** A civil date and time without a time zone, `YYYY-MM-DDTHH:MM:SS[.ffffff]`. */
+    datetime: (value) => typed("DATETIME", value),
+    timestamp: (value) => typed("TIMESTAMP", timestamp(value)),
+    /** An array of one element type; needed for empty arrays and non-default element types. */
+    array: (type, values) => ({
+        [TYPED]: true,
+        type,
+        values: values.map((value) => scalar(value, "array element").value),
+    }),
+};
+function isTyped(value) {
+    return typeof value === "object" && value !== null && TYPED in value;
+}
+function scalar(value, name) {
+    switch (typeof value) {
+        case "string":
+            return { type: "STRING", value };
+        case "boolean":
+            return { type: "BOOL", value: String(value) };
+        case "bigint":
+            return { type: "INT64", value: String(value) };
+        case "number":
+            return Number.isSafeInteger(value)
+                ? { type: "INT64", value: String(value) }
+                : { type: "FLOAT64", value: String(value) };
+        default:
+            if (value instanceof Date) {
+                return { type: "TIMESTAMP", value: timestamp(value) };
+            }
+            throw new TypeError(`Query parameter "${name}" must be a string, number, bigint, boolean, Date, or sql.* value; ` +
+                "use SQL NULL in the query text instead of a null parameter.");
+    }
+}
+/** Infers warehouse types for named parameters and validates their names. */
+export function encodeParameters(parameters) {
+    if (parameters === undefined) {
+        return [];
+    }
+    return Object.entries(parameters).map(([name, value]) => {
+        if (!NAME.test(name)) {
+            throw new TypeError(`Query parameter name "${name}" must start with a letter or underscore and contain only letters, digits, and underscores.`);
+        }
+        if (isTyped(value)) {
+            return value.values === undefined
+                ? { name, type: value.type, value: value.value ?? "" }
+                : { name, type: value.type, values: value.values };
+        }
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                throw new TypeError(`Query parameter "${name}" is an empty array; use sql.array(type, []) to declare its element type.`);
+            }
+            const items = value.map((item) => scalar(item, name));
+            const type = items.every((item) => item.type === items[0]?.type)
+                ? items[0].type
+                : items.every((item) => item.type === "INT64" || item.type === "FLOAT64")
+                    ? "FLOAT64"
+                    : undefined;
+            if (type === undefined) {
+                throw new TypeError(`Query parameter "${name}" mixes element types; use sql.array(type, values).`);
+            }
+            return { name, type, values: items.map((item) => item.value) };
+        }
+        return { name, ...scalar(value, name) };
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.1.0",
-  "description": "Sign-in and session handling for SegmentStream workspace apps built with Next.js.",
+  "version": "0.2.0",
+  "description": "Sign-in, sessions, and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",
   "homepage": "https://segmentstream.com",