Before you start
Workflow
- 1Choose an existing connector, dataset, or published Data Flow output. Inspect it with sources.get before choosing table and field names. If revenue needs reusable joins or business rules, implement and verify those in a Data Flow first.
- 2Create a React app using the deploy-app guide. Have an administrator approve whole-source Read for the app and each intended viewer, plus access to the app itself.
- 3Replace src/App.tsx with the example below and set the verified source ID and SQL table name. This example assumes orders has customer_name and numeric amount columns in one currency, with one row per order. Apply your agreed revenue definition before using it for business decisions.
- 4Build and publish using the deploy-app guide. Open the hosted URL as an intended viewer; the browser uses their Permute session, not an API key.
- 5Verify totals against the source, test an empty result, and confirm denial for a viewer without source access. Revoke a grant from an already-open app and verify its next refresh fails.
Project setup
bun add @permute/sdk@^0.13.0 zod
Example: revenue by customer
Bundle this component into the app frontend. It reads one bounded aggregate query, validates the returned rows, and displays a total and customer breakdown. The table name orders is illustrative: replace it with the exact identifier from source discovery. Source IDs are configuration, not secrets; never include an authoring API key in the bundle.
The example rejects truncated results so the summary cannot silently omit customers. For larger customer lists, query the overall total separately and add server-side pagination for detail rows. Refresh re-queries the available source output; it does not sync a connector or run a Data Flow. Show source freshness separately when viewers need to know how current the underlying data is.
import { useEffect, useState } from 'react';
import { PermuteAppClient } from '@permute/sdk/app';
import { z } from 'zod';
const app = new PermuteAppClient();
const sourceId = 'REPLACE_WITH_VERIFIED_SOURCE_ID';
const rowsSchema = z.array(z.object({
customer: z.string(),
revenue: z.coerce.number().finite(),
}));
type RevenueRow = z.infer<typeof rowsSchema>[number];
const number = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 });
export default function App() {
const [rows, setRows] = useState<RevenueRow[]>([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [refresh, setRefresh] = useState(0);
useEffect(() => {
let active = true;
setLoading(true);
setError(null);
async function load() {
const result = await app.query({
sourceIds: [sourceId],
sql: 'SELECT COALESCE(customer_name, \'Unassigned\') AS customer, ' +
'COALESCE(SUM(amount), 0) AS revenue FROM orders ' +
'GROUP BY 1 ORDER BY revenue DESC, customer',
limit: 100,
});
if (result.truncated) throw new Error('Too many customers; add pagination before showing totals.');
return rowsSchema.parse(result.rows);
}
void load()
.then((data) => { if (active) setRows(data); })
.catch((cause: unknown) => {
if (active) setError(cause instanceof Error ? cause.message : 'Unable to load revenue');
})
.finally(() => { if (active) setLoading(false); });
return () => { active = false; };
}, [refresh]);
return (
<main>
<h1>Revenue by customer</h1>
<button disabled={loading} onClick={() => setRefresh((value) => value + 1)}>Refresh</button>
{loading ? <p role="status">Loading revenue…</p> : error ? <p role="alert">{error}</p> :
rows.length === 0 ? <p>No orders are available.</p> : <>
<h2>Total: {number.format(rows.reduce((sum, row) => sum + row.revenue, 0))}</h2>
<table>
<caption>Revenue in the source currency</caption>
<thead><tr><th scope="col">Customer</th><th scope="col">Revenue</th></tr></thead>
<tbody>{rows.map((row) => <tr key={row.customer}>
<th scope="row">{row.customer}</th><td>{number.format(row.revenue)}</td>
</tr>)}</tbody>
</table>
</>}
</main>
);
}Add charts, filters, and shared definitions
Render the validated aggregates with a chart library bundled in your build, and add filters appropriate to the question. Browser filters control presentation; they do not restrict source access. Use separately permissioned Data Flow outputs when audiences need different subsets.
Keep shared calculations in the governed source so the app and its built-in assistant use the same definitions. The assistant can query permitted sources but cannot see the rendered page or unsaved filters. Ordinary dashboard reads use app.query(); Business Actions are for deliberately delegated logic or explicitly requested writes.