@makoai/app-sdk 2.2.0 → 2.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -5
- package/credentials.d.ts +3 -0
- package/credentials.js +4 -0
- package/index.d.ts +79 -2
- package/index.js +314 -62
- package/package.json +2 -2
- package/vite.d.ts +36 -3
- package/vite.js +284 -27
package/README.md
CHANGED
|
@@ -19,8 +19,25 @@ const { data, loading, error } = useQuery("latest_sales");
|
|
|
19
19
|
// Analytical SQL over every binding (DuckDB-WASM in the browser; table
|
|
20
20
|
// names are binding names).
|
|
21
21
|
const totals = useDuckDB("select country, sum(revenue) r from latest_sales group by 1");
|
|
22
|
+
|
|
23
|
+
// Rematerialize on demand: re-runs the binding's query on the warehouse,
|
|
24
|
+
// then every hook reading it re-renders with the new rows. The old rows
|
|
25
|
+
// stay on screen while `refreshing` is true.
|
|
26
|
+
const { refresh, refreshing } = useQuery("latest_sales");
|
|
27
|
+
<button onClick={() => refresh().catch(e => alert(e.message))} disabled={refreshing}>
|
|
28
|
+
Refresh
|
|
29
|
+
</button>
|
|
22
30
|
```
|
|
23
31
|
|
|
32
|
+
`useDuckDB(...).refresh()` refreshes every binding; `refreshBinding(name)` /
|
|
33
|
+
`refreshBindings()` do the same outside a component. A refresh POSTs to
|
|
34
|
+
`__data/<name>/refresh`, the data URL's sibling, so whoever serves the app's
|
|
35
|
+
data (Mako, the sandbox dev server, the Vite plugin below) rebuilds it with
|
|
36
|
+
its own authorization: a signed-in member can always refresh; a public share
|
|
37
|
+
only when its owner enabled live queries, and at most once every few minutes
|
|
38
|
+
per binding. A refused refresh rejects with `status` (403, 429 + `retryAfterMs`)
|
|
39
|
+
or 502 with the query's error.
|
|
40
|
+
|
|
24
41
|
`useLocation` / `useSearchParams` / `navigate` keep filter state in the URL;
|
|
25
42
|
`useTheme` follows the OS preference. Theme tokens (`--background`,
|
|
26
43
|
`--chart-1`, …) match the ones the scaffold's `styles.css` declares.
|
|
@@ -28,6 +45,48 @@ const totals = useDuckDB("select country, sum(revenue) r from latest_sales group
|
|
|
28
45
|
Data arrives from `__data/<name>.parquet`, relative to the page — the same
|
|
29
46
|
path in Mako's sandbox, in a published app, and on a laptop.
|
|
30
47
|
|
|
48
|
+
### Who is looking: `useViewer()`
|
|
49
|
+
|
|
50
|
+
```tsx
|
|
51
|
+
import { useViewer } from "@makoai/app-sdk";
|
|
52
|
+
|
|
53
|
+
const { viewer, loading } = useViewer();
|
|
54
|
+
// viewer === null → anonymous share link (or still loading)
|
|
55
|
+
// viewer.email → "sam@acme.com"
|
|
56
|
+
// viewer.workspace.role → "owner" | "admin" | "member" | "viewer" | null
|
|
57
|
+
// viewer.app.role → "owner" | "editor" | "viewer" | null
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Mako resolves the viewer server-side from the session or the signed view
|
|
61
|
+
token — the page cannot forge it — and reports only what the platform
|
|
62
|
+
knows: identity, the workspace and the person's **access** role in it, and
|
|
63
|
+
their role on this app. There is no job title, team or country in the
|
|
64
|
+
platform, on purpose: those are your data. Put a roster in a binding and
|
|
65
|
+
join on the email:
|
|
66
|
+
|
|
67
|
+
```sql
|
|
68
|
+
-- bindings/viewers.sql
|
|
69
|
+
SELECT lower(email) AS email, team, country, is_lead FROM hr.people
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
```tsx
|
|
73
|
+
const { viewer } = useViewer();
|
|
74
|
+
const me = useDuckDB(
|
|
75
|
+
viewer ? `select * from viewers where email = '${viewer.email.replace(/'/g, "''")}'` : "select 1 where false",
|
|
76
|
+
);
|
|
77
|
+
const board = useDuckDB(
|
|
78
|
+
me.data?.[0]?.is_lead
|
|
79
|
+
? "select * from pipeline"
|
|
80
|
+
: `select * from pipeline where team = '${me.data?.[0]?.team ?? ""}'`,
|
|
81
|
+
);
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Keep the roster binding to the columns the app needs for its logic: every
|
|
85
|
+
binding the app can read is downloaded whole into the viewer's browser, so
|
|
86
|
+
this shapes the UI rather than enforcing access. Who may *open* the app is
|
|
87
|
+
the app's access setting in Mako; server-side row filtering is a follow-up
|
|
88
|
+
on the same identity (apps.md §28).
|
|
89
|
+
|
|
31
90
|
## In `vite.config.ts`
|
|
32
91
|
|
|
33
92
|
```ts
|
|
@@ -37,13 +96,42 @@ export default defineConfig({ plugins: [react(), makoData()] });
|
|
|
37
96
|
```
|
|
38
97
|
|
|
39
98
|
`makoData()` answers `__data/index.json` (the app's `bindings/*.sql`) and
|
|
40
|
-
`__data/<name>.parquet` during `vite dev`
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
99
|
+
`__data/<name>.parquet` during `vite dev` from the Mako API, and what it asks
|
|
100
|
+
for is **your local binding file**: it sends the text of
|
|
101
|
+
`bindings/<name>.sql` and gets back the parquet of exactly that query, run
|
|
102
|
+
read-only through the workspace connection its front matter names. When the
|
|
103
|
+
text is the committed binding, that is the app's stored artifact (built on
|
|
104
|
+
first request if it never was); when you have edited it, Mako builds a draft
|
|
105
|
+
from your text and hands it back without storing it — nobody else, and no
|
|
106
|
+
published viewer, ever sees uncommitted SQL. Building needs edit access to the
|
|
107
|
+
app; read-only members get committed artifacts. `POST __data/<name>/refresh`
|
|
108
|
+
(the SDK's `refresh()`) rebuilds from the local text on demand.
|
|
109
|
+
|
|
110
|
+
Results are cached under `node_modules/.mako-data/` for five minutes
|
|
111
|
+
(`revalidateMs`; `?refresh` bypasses), next to a fingerprint of the text they
|
|
112
|
+
were built from: after an edit the cache is never served, however long
|
|
113
|
+
`revalidateMs` is, and while the API is unreachable a stale copy is served
|
|
114
|
+
only if it was built from the same text. It is `apply: "serve"` only —
|
|
45
115
|
production builds never load it.
|
|
46
116
|
|
|
117
|
+
### dbt models you are still building
|
|
118
|
+
|
|
119
|
+
A binding linked to dbt (`-- dbt_project: <id>`) writes `{{ dbt_schema }}`,
|
|
120
|
+
which renders to the production schema. To preview models you built into
|
|
121
|
+
your own dbt environment, point the dev server at it:
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
makoData({ dbtEnvironment: "joan" }) // or MAKO_DBT_ENV=joan in the repo's .env
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
The environment must exist in the linked dbt project (`dbt/environments.yml`),
|
|
128
|
+
and a personal environment (`owner_user_id`) renders only for its owner.
|
|
129
|
+
These builds are drafts too: never stored, never what a published app reads.
|
|
130
|
+
|
|
131
|
+
It also answers `__data/viewer.json` (you, as Mako sees you), and
|
|
132
|
+
`MAKO_VIEWER_AS=<email>` — in the environment or the repo's `.env` —
|
|
133
|
+
previews the app as that member instead (editors of the app only).
|
|
134
|
+
|
|
47
135
|
Credentials, in order: `MAKO_API_URL` / `MAKO_API_KEY` in the environment,
|
|
48
136
|
then in the repo-root `.env`. The workspace id comes from
|
|
49
137
|
`.mako/workspace.json` (or `MAKO_WORKSPACE_ID`). Without a key the app runs
|
package/credentials.d.ts
CHANGED
package/credentials.js
CHANGED
|
@@ -11,6 +11,10 @@ import fs from "node:fs";
|
|
|
11
11
|
import os from "node:os";
|
|
12
12
|
import path from "node:path";
|
|
13
13
|
|
|
14
|
+
/** The hosted Mako API — the default wherever nothing overrides it
|
|
15
|
+
* (MAKO_API_URL, .env, .mako/workspace.json apiUrl, or an explicit option). */
|
|
16
|
+
export const HOSTED_API_URL = "https://app.mako.ai";
|
|
17
|
+
|
|
14
18
|
export const CREDENTIALS_PATH =
|
|
15
19
|
process.env.MAKO_CREDENTIALS_FILE ||
|
|
16
20
|
path.join(os.homedir(), ".mako", "credentials.json");
|
package/index.d.ts
CHANGED
|
@@ -1,10 +1,37 @@
|
|
|
1
1
|
import type * as React from "react";
|
|
2
2
|
|
|
3
|
+
/** What a refresh built — the server's answer to `POST __data/<name>/refresh`. */
|
|
4
|
+
export interface RefreshResult {
|
|
5
|
+
binding: string;
|
|
6
|
+
/** "live" bindings have no artifact; the refresh just re-fetched them. */
|
|
7
|
+
materialization: "parquet" | "live";
|
|
8
|
+
rowCount?: number;
|
|
9
|
+
byteSize?: number;
|
|
10
|
+
/** ISO 8601; absent for a live binding. */
|
|
11
|
+
materializedAt?: string;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** Why a refresh was refused or failed. */
|
|
15
|
+
export interface RefreshError extends Error {
|
|
16
|
+
/** 403: not allowed here; 404: no such binding; 429: refreshed too recently; 502: the query failed. */
|
|
17
|
+
status?: number;
|
|
18
|
+
/** With 429: how long until the next refresh is accepted. */
|
|
19
|
+
retryAfterMs?: number;
|
|
20
|
+
}
|
|
21
|
+
|
|
3
22
|
export interface QueryState<Row = Record<string, unknown>> {
|
|
4
23
|
data: Row[] | null;
|
|
5
24
|
error: string | null;
|
|
25
|
+
/** First load (or a new query): no rows yet. */
|
|
6
26
|
loading: boolean;
|
|
27
|
+
/** A refresh is in flight; `data` still holds the previous rows. */
|
|
28
|
+
refreshing: boolean;
|
|
7
29
|
truncated: boolean;
|
|
30
|
+
/**
|
|
31
|
+
* Rematerialize the data behind this query and re-run it. Rejects with a
|
|
32
|
+
* `RefreshError` — the rows on screen are untouched when it does.
|
|
33
|
+
*/
|
|
34
|
+
refresh: () => Promise<RefreshResult | RefreshResult[]>;
|
|
8
35
|
}
|
|
9
36
|
export interface DuckDBState<Row = Record<string, unknown>>
|
|
10
37
|
extends QueryState<Row> {
|
|
@@ -26,13 +53,63 @@ export interface MakoLocation {
|
|
|
26
53
|
export function useQuery<Row = Record<string, unknown>>(
|
|
27
54
|
name: string,
|
|
28
55
|
opts?: QueryOptions,
|
|
29
|
-
): QueryState<Row
|
|
56
|
+
): QueryState<Row> & { refresh: () => Promise<RefreshResult> };
|
|
30
57
|
|
|
31
58
|
/** Analytical SQL over the app's bindings; table names are binding names. */
|
|
32
59
|
export function useDuckDB<Row = Record<string, unknown>>(
|
|
33
60
|
sql: string,
|
|
34
61
|
opts?: QueryOptions,
|
|
35
|
-
): DuckDBState<Row
|
|
62
|
+
): DuckDBState<Row> & { refresh: () => Promise<RefreshResult[]> };
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Rematerialize one binding on demand and reload it everywhere it is used.
|
|
66
|
+
* Concurrent calls for the same binding share one request.
|
|
67
|
+
*/
|
|
68
|
+
export function refreshBinding(name: string): Promise<RefreshResult>;
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Refresh several bindings — all of them when `names` is omitted. Every one
|
|
72
|
+
* is attempted; rejects after they settle if any failed (`failures` lists
|
|
73
|
+
* them).
|
|
74
|
+
*/
|
|
75
|
+
export function refreshBindings(
|
|
76
|
+
names?: string[],
|
|
77
|
+
): Promise<RefreshResult[]>;
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* The person viewing the app, as Mako resolved them from the session or the
|
|
81
|
+
* signed view token (apps.md §28). Only what the platform knows: identity,
|
|
82
|
+
* the workspace and their ACCESS role in it, their role on this app. Look
|
|
83
|
+
* up anything else (team, territory, …) in the warehouse by `email`.
|
|
84
|
+
*/
|
|
85
|
+
export interface Viewer {
|
|
86
|
+
id: string;
|
|
87
|
+
/** Signed-in email, lowercased. */
|
|
88
|
+
email: string;
|
|
89
|
+
workspace: {
|
|
90
|
+
id: string;
|
|
91
|
+
name: string;
|
|
92
|
+
/** Access role in the workspace; null when not a member. */
|
|
93
|
+
role: "owner" | "admin" | "member" | "viewer" | null;
|
|
94
|
+
};
|
|
95
|
+
app: {
|
|
96
|
+
id: string;
|
|
97
|
+
slug: string | null;
|
|
98
|
+
/** What they may do to this app. */
|
|
99
|
+
role: "owner" | "editor" | "viewer" | null;
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
export interface ViewerState {
|
|
103
|
+
/** null while loading, on an anonymous share, or on an older server. */
|
|
104
|
+
viewer: Viewer | null;
|
|
105
|
+
loading: boolean;
|
|
106
|
+
error: string | null;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Who is looking. The app decides what that means for its UI and data. */
|
|
110
|
+
export function useViewer(): ViewerState;
|
|
111
|
+
/** The same, outside a component; resolved once per page. */
|
|
112
|
+
export function getViewer(): Promise<Viewer | null>;
|
|
36
113
|
|
|
37
114
|
export function useTheme(): { theme: "light" | "dark" };
|
|
38
115
|
export function useLocation(): MakoLocation;
|
package/index.js
CHANGED
|
@@ -23,38 +23,210 @@ function getDb() {
|
|
|
23
23
|
return dbPromise;
|
|
24
24
|
}
|
|
25
25
|
|
|
26
|
+
// The server answers failures with JSON { error, hint, retryAfterMs } —
|
|
27
|
+
// show that, not a bare status code (and never let it reach DuckDB, where it
|
|
28
|
+
// would surface as a baffling Catalog Error).
|
|
29
|
+
async function responseError(res, what) {
|
|
30
|
+
let body = null;
|
|
31
|
+
try {
|
|
32
|
+
body = await res.json();
|
|
33
|
+
} catch {
|
|
34
|
+
/* not JSON (e.g. a published build with no artifact) */
|
|
35
|
+
}
|
|
36
|
+
const detail = body ? [body.error, body.hint].filter(Boolean).join(" — ") : "";
|
|
37
|
+
const error = new Error(what + " (HTTP " + res.status + ")" + (detail ? ": " + detail : ""));
|
|
38
|
+
error.status = res.status;
|
|
39
|
+
if (body && typeof body.retryAfterMs === "number") error.retryAfterMs = body.retryAfterMs;
|
|
40
|
+
return error;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
async function loadBinding(name, bust) {
|
|
44
|
+
const res = await fetch(
|
|
45
|
+
"__data/" + encodeURIComponent(name) + ".parquet" + (bust ? "?refresh=" + Date.now() : ""),
|
|
46
|
+
);
|
|
47
|
+
if (!res.ok) {
|
|
48
|
+
throw await responseError(res, 'Data for binding "' + name + '" could not be loaded');
|
|
49
|
+
}
|
|
50
|
+
const buf = new Uint8Array(await res.arrayBuffer());
|
|
51
|
+
const db = await getDb();
|
|
52
|
+
if (bust) await db.dropFile(name + ".parquet").catch(() => {});
|
|
53
|
+
await db.registerFileBuffer(name + ".parquet", buf);
|
|
54
|
+
const conn = await db.connect();
|
|
55
|
+
try {
|
|
56
|
+
// A view per binding so SQL can name tables by binding name.
|
|
57
|
+
await conn.query(
|
|
58
|
+
'CREATE OR REPLACE VIEW "' + name.replace(/"/g, '""') +
|
|
59
|
+
"\" AS SELECT * FROM read_parquet('" + name + ".parquet')",
|
|
60
|
+
);
|
|
61
|
+
} finally {
|
|
62
|
+
await conn.close();
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
26
66
|
const registered = new Map(); // name -> Promise<void>
|
|
27
67
|
function registerBinding(name) {
|
|
28
68
|
if (!registered.has(name)) {
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
const res = await fetch("__data/" + encodeURIComponent(name) + ".parquet");
|
|
33
|
-
if (!res.ok) {
|
|
34
|
-
registered.delete(name);
|
|
35
|
-
throw new Error(
|
|
36
|
-
'Binding "' + name + '" is not materialized (HTTP ' + res.status + ")",
|
|
37
|
-
);
|
|
38
|
-
}
|
|
39
|
-
const buf = new Uint8Array(await res.arrayBuffer());
|
|
40
|
-
const db = await getDb();
|
|
41
|
-
await db.registerFileBuffer(name + ".parquet", buf);
|
|
42
|
-
const conn = await db.connect();
|
|
43
|
-
try {
|
|
44
|
-
// A view per binding so SQL can name tables by binding name.
|
|
45
|
-
await conn.query(
|
|
46
|
-
'CREATE OR REPLACE VIEW "' + name.replace(/"/g, '""') +
|
|
47
|
-
"\" AS SELECT * FROM read_parquet('" + name + ".parquet')",
|
|
48
|
-
);
|
|
49
|
-
} finally {
|
|
50
|
-
await conn.close();
|
|
51
|
-
}
|
|
52
|
-
})(),
|
|
53
|
-
);
|
|
69
|
+
const load = loadBinding(name, false);
|
|
70
|
+
registered.set(name, load);
|
|
71
|
+
load.catch(() => registered.delete(name));
|
|
54
72
|
}
|
|
55
73
|
return registered.get(name);
|
|
56
74
|
}
|
|
57
75
|
|
|
76
|
+
/** Replace a binding's loaded bytes with what the server has now. */
|
|
77
|
+
async function reloadBinding(name) {
|
|
78
|
+
// Let a load in flight settle first, or its (older) bytes could land after
|
|
79
|
+
// the fresh ones and win.
|
|
80
|
+
const previous = registered.get(name);
|
|
81
|
+
if (previous) await previous.catch(() => {});
|
|
82
|
+
const load = loadBinding(name, true);
|
|
83
|
+
registered.set(name, load);
|
|
84
|
+
try {
|
|
85
|
+
await load;
|
|
86
|
+
} catch (error) {
|
|
87
|
+
registered.delete(name);
|
|
88
|
+
throw error;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
// ---------------------------------------------------------------------------
|
|
93
|
+
// Refresh — rematerialize a binding on demand. The runtime POSTs to the
|
|
94
|
+
// data URL's sibling, `__data/<name>/refresh`, and every server that answers
|
|
95
|
+
// `__data/<name>.parquet` (Mako's viewer, preview and share routes, the
|
|
96
|
+
// sandbox dev server, the laptop Vite plugin) rebuilds the binding behind
|
|
97
|
+
// it, with its own authorization. The runtime then reloads the bytes and
|
|
98
|
+
// bumps a version every query hook depends on, so the page re-renders with
|
|
99
|
+
// the new rows — and keeps the old ones on screen until they arrive.
|
|
100
|
+
// ---------------------------------------------------------------------------
|
|
101
|
+
const bindingListeners = new Set();
|
|
102
|
+
let bindingState = { version: 0, refreshing: new Set() };
|
|
103
|
+
function setBindingState(next) {
|
|
104
|
+
bindingState = next;
|
|
105
|
+
for (const l of [...bindingListeners]) l();
|
|
106
|
+
}
|
|
107
|
+
function subscribeBindings(l) {
|
|
108
|
+
bindingListeners.add(l);
|
|
109
|
+
return () => bindingListeners.delete(l);
|
|
110
|
+
}
|
|
111
|
+
function getBindingState() {
|
|
112
|
+
return bindingState;
|
|
113
|
+
}
|
|
114
|
+
function useBindingState() {
|
|
115
|
+
return React.useSyncExternalStore(subscribeBindings, getBindingState, getBindingState);
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const refreshes = new Map(); // name -> Promise<RefreshResult>
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Rebuild one binding's data and reload it. Resolves with what the server
|
|
122
|
+
* built; rejects with an Error carrying `status` (403: not allowed here,
|
|
123
|
+
* 429: refreshed too recently — see `retryAfterMs`, 502: the query failed —
|
|
124
|
+
* the message says why). Concurrent calls for the same binding share one
|
|
125
|
+
* request.
|
|
126
|
+
*/
|
|
127
|
+
export function refreshBinding(name) {
|
|
128
|
+
const pending = refreshes.get(name);
|
|
129
|
+
if (pending) return pending;
|
|
130
|
+
const run = (async () => {
|
|
131
|
+
const res = await fetch("__data/" + encodeURIComponent(name) + "/refresh", { method: "POST" });
|
|
132
|
+
if (!res.ok) {
|
|
133
|
+
throw await responseError(res, 'Binding "' + name + '" could not be refreshed');
|
|
134
|
+
}
|
|
135
|
+
const body = await res.json();
|
|
136
|
+
await reloadBinding(name);
|
|
137
|
+
setBindingState({ ...bindingState, version: bindingState.version + 1 });
|
|
138
|
+
return {
|
|
139
|
+
binding: name,
|
|
140
|
+
materialization: body.materialization,
|
|
141
|
+
rowCount: body.rowCount,
|
|
142
|
+
byteSize: body.byteSize,
|
|
143
|
+
materializedAt: body.materializedAt,
|
|
144
|
+
};
|
|
145
|
+
})();
|
|
146
|
+
refreshes.set(name, run);
|
|
147
|
+
setBindingState({ ...bindingState, refreshing: new Set([...bindingState.refreshing, name]) });
|
|
148
|
+
run
|
|
149
|
+
.finally(() => {
|
|
150
|
+
refreshes.delete(name);
|
|
151
|
+
const refreshing = new Set(bindingState.refreshing);
|
|
152
|
+
refreshing.delete(name);
|
|
153
|
+
setBindingState({ ...bindingState, refreshing });
|
|
154
|
+
})
|
|
155
|
+
.catch(() => {
|
|
156
|
+
/* the caller's copy of `run` carries the rejection */
|
|
157
|
+
});
|
|
158
|
+
return run;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Refresh several bindings at once — every staged binding when no names are
|
|
163
|
+
* given (what `useDuckDB(...).refresh()` does). All of them are attempted;
|
|
164
|
+
* if any failed, rejects after the rest settle with `failures` listing them.
|
|
165
|
+
*/
|
|
166
|
+
export async function refreshBindings(names) {
|
|
167
|
+
const list = names ?? (await bindingIndex());
|
|
168
|
+
const settled = await Promise.allSettled(list.map(refreshBinding));
|
|
169
|
+
const failures = settled
|
|
170
|
+
.map((s, i) => (s.status === "rejected" ? { binding: list[i], error: s.reason } : null))
|
|
171
|
+
.filter(Boolean);
|
|
172
|
+
if (failures.length) {
|
|
173
|
+
const error = new Error(
|
|
174
|
+
failures.map(f => (f.error instanceof Error ? f.error.message : String(f.error))).join("; "),
|
|
175
|
+
);
|
|
176
|
+
error.failures = failures;
|
|
177
|
+
throw error;
|
|
178
|
+
}
|
|
179
|
+
return settled.map(s => s.value);
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
// ---------------------------------------------------------------------------
|
|
183
|
+
// Viewer — who is looking. `__data/viewer.json` is answered per request by
|
|
184
|
+
// whoever serves the app (Mako's published/preview routes from the session
|
|
185
|
+
// or the signed token, the Vite plugin from the API), so the app cannot
|
|
186
|
+
// forge it. `null` on an anonymous share link, and on servers that predate
|
|
187
|
+
// it (404). Mako says only what it knows: id, email, the workspace and the
|
|
188
|
+
// person's ACCESS role in it, their role on this app. Anything else about
|
|
189
|
+
// the person is data the app looks up in the warehouse by email.
|
|
190
|
+
// ---------------------------------------------------------------------------
|
|
191
|
+
let viewerPromise = null;
|
|
192
|
+
function normalizeViewer(body) {
|
|
193
|
+
if (!body || typeof body !== "object" || typeof body.email !== "string") return null;
|
|
194
|
+
const ws = body.workspace && typeof body.workspace === "object" ? body.workspace : {};
|
|
195
|
+
const app = body.app && typeof body.app === "object" ? body.app : {};
|
|
196
|
+
return {
|
|
197
|
+
id: typeof body.id === "string" ? body.id : "",
|
|
198
|
+
email: body.email,
|
|
199
|
+
workspace: {
|
|
200
|
+
id: typeof ws.id === "string" ? ws.id : "",
|
|
201
|
+
name: typeof ws.name === "string" ? ws.name : "",
|
|
202
|
+
role: typeof ws.role === "string" ? ws.role : null,
|
|
203
|
+
},
|
|
204
|
+
app: {
|
|
205
|
+
id: typeof app.id === "string" ? app.id : "",
|
|
206
|
+
slug: typeof app.slug === "string" ? app.slug : null,
|
|
207
|
+
role: typeof app.role === "string" ? app.role : null,
|
|
208
|
+
},
|
|
209
|
+
};
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** The viewer, once per page. Resolves to null when nobody is known. */
|
|
213
|
+
export function getViewer() {
|
|
214
|
+
viewerPromise ??= fetch("__data/viewer.json").then(async r => {
|
|
215
|
+
if (r.status === 404) return null;
|
|
216
|
+
const body = await r.json().catch(() => null);
|
|
217
|
+
if (!r.ok) {
|
|
218
|
+
throw new Error(
|
|
219
|
+
body && body.error ? String(body.error) : "Viewer lookup failed (HTTP " + r.status + ")",
|
|
220
|
+
);
|
|
221
|
+
}
|
|
222
|
+
return normalizeViewer(body);
|
|
223
|
+
});
|
|
224
|
+
viewerPromise.catch(() => {
|
|
225
|
+
viewerPromise = null;
|
|
226
|
+
});
|
|
227
|
+
return viewerPromise;
|
|
228
|
+
}
|
|
229
|
+
|
|
58
230
|
/** Names of every staged binding — written by the dev server next to the
|
|
59
231
|
* parquet files. Absent (older servers, published builds): empty list. */
|
|
60
232
|
let indexPromise = null;
|
|
@@ -116,38 +288,40 @@ async function runSql(sql, rowLimit) {
|
|
|
116
288
|
}
|
|
117
289
|
}
|
|
118
290
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
291
|
+
const EMPTY = {
|
|
292
|
+
data: null,
|
|
293
|
+
fields: null,
|
|
294
|
+
error: null,
|
|
295
|
+
loading: true,
|
|
296
|
+
truncated: false,
|
|
297
|
+
rowCount: null,
|
|
298
|
+
refreshing: false,
|
|
299
|
+
};
|
|
300
|
+
|
|
301
|
+
// Runs `run` when `deps` change (a fresh query: rows reset, `loading`), and
|
|
302
|
+
// again when a refresh lands (`refreshing`: the rows already on screen stay
|
|
303
|
+
// until the new ones arrive — a dashboard must not blink to empty on every
|
|
304
|
+
// refresh). `isRefreshing` says whether a refresh in flight concerns this
|
|
305
|
+
// query, so `refreshing` is true from the click, not only from the reload.
|
|
306
|
+
function useAsyncQuery(run, deps, isRefreshing) {
|
|
307
|
+
const bindings = useBindingState();
|
|
308
|
+
const [state, setState] = React.useState(EMPTY);
|
|
309
|
+
const seenVersion = React.useRef(bindings.version);
|
|
128
310
|
React.useEffect(() => {
|
|
129
311
|
let active = true;
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
error: null,
|
|
134
|
-
loading: true,
|
|
135
|
-
truncated: false,
|
|
136
|
-
rowCount: null,
|
|
137
|
-
});
|
|
312
|
+
const isRefresh = seenVersion.current !== bindings.version;
|
|
313
|
+
seenVersion.current = bindings.version;
|
|
314
|
+
setState(s => (isRefresh && s.data !== null ? { ...s, refreshing: true } : EMPTY));
|
|
138
315
|
run().then(
|
|
139
316
|
result => {
|
|
140
|
-
if (active) setState({ ...result, error: null, loading: false });
|
|
317
|
+
if (active) setState({ ...result, error: null, loading: false, refreshing: false });
|
|
141
318
|
},
|
|
142
319
|
error => {
|
|
143
320
|
if (active)
|
|
144
321
|
setState({
|
|
145
|
-
|
|
146
|
-
fields: null,
|
|
322
|
+
...EMPTY,
|
|
147
323
|
error: error instanceof Error ? error.message : String(error),
|
|
148
324
|
loading: false,
|
|
149
|
-
truncated: false,
|
|
150
|
-
rowCount: null,
|
|
151
325
|
});
|
|
152
326
|
},
|
|
153
327
|
);
|
|
@@ -155,32 +329,95 @@ function useAsyncQuery(run, deps) {
|
|
|
155
329
|
active = false;
|
|
156
330
|
};
|
|
157
331
|
// eslint-disable-next-line react-hooks/exhaustive-deps
|
|
158
|
-
}, deps);
|
|
159
|
-
return
|
|
332
|
+
}, [...deps, bindings.version]);
|
|
333
|
+
return {
|
|
334
|
+
...state,
|
|
335
|
+
refreshing: state.refreshing || isRefreshing(bindings.refreshing),
|
|
336
|
+
};
|
|
160
337
|
}
|
|
161
338
|
|
|
162
339
|
export function useQuery(name, opts) {
|
|
163
340
|
const rowLimit = opts ? opts.rowLimit : undefined;
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
341
|
+
const state = useAsyncQuery(
|
|
342
|
+
async () => {
|
|
343
|
+
await registerBinding(name);
|
|
344
|
+
const r = await runSql(
|
|
345
|
+
'SELECT * FROM "' + name.replace(/"/g, '""') + '"',
|
|
346
|
+
rowLimit,
|
|
347
|
+
);
|
|
348
|
+
return { data: r.rows, fields: r.fields, truncated: r.truncated, rowCount: r.rowCount };
|
|
349
|
+
},
|
|
350
|
+
[name, rowLimit],
|
|
351
|
+
refreshing => refreshing.has(name),
|
|
352
|
+
);
|
|
353
|
+
const refresh = React.useCallback(() => refreshBinding(name), [name]);
|
|
354
|
+
return { ...state, refresh };
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
/**
|
|
358
|
+
* Who is looking at the app: `{ viewer, loading, error }`. `viewer` is null
|
|
359
|
+
* while loading, on an anonymous share link, and when the server does not
|
|
360
|
+
* know. Join `viewer.email` against your own roster binding for anything
|
|
361
|
+
* beyond identity and access role — that is the app's call, not Mako's.
|
|
362
|
+
*/
|
|
363
|
+
export function useViewer() {
|
|
364
|
+
const [state, setState] = React.useState({ viewer: null, loading: true, error: null });
|
|
365
|
+
React.useEffect(() => {
|
|
366
|
+
let active = true;
|
|
367
|
+
getViewer().then(
|
|
368
|
+
viewer => {
|
|
369
|
+
if (active) setState({ viewer, loading: false, error: null });
|
|
370
|
+
},
|
|
371
|
+
error => {
|
|
372
|
+
if (active) {
|
|
373
|
+
setState({
|
|
374
|
+
viewer: null,
|
|
375
|
+
loading: false,
|
|
376
|
+
error: error instanceof Error ? error.message : String(error),
|
|
377
|
+
});
|
|
378
|
+
}
|
|
379
|
+
},
|
|
169
380
|
);
|
|
170
|
-
return
|
|
171
|
-
|
|
381
|
+
return () => {
|
|
382
|
+
active = false;
|
|
383
|
+
};
|
|
384
|
+
}, []);
|
|
385
|
+
return state;
|
|
172
386
|
}
|
|
173
387
|
|
|
174
388
|
export function useDuckDB(sql, opts) {
|
|
175
389
|
const rowLimit = opts ? opts.rowLimit : undefined;
|
|
176
|
-
|
|
390
|
+
const state = useAsyncQuery(async () => {
|
|
177
391
|
// Register everything the server staged, so SQL can join across
|
|
178
|
-
// bindings by name without declaring them first.
|
|
392
|
+
// bindings by name without declaring them first. A binding that fails to
|
|
393
|
+
// load must not sink the whole query set silently: remember why, and when
|
|
394
|
+
// the SQL then fails (typically DuckDB's "Table … does not exist"),
|
|
395
|
+
// surface the load failure — it is the actual cause.
|
|
179
396
|
const names = await bindingIndex();
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
397
|
+
const failures = new Map();
|
|
398
|
+
await Promise.all(
|
|
399
|
+
names.map(n => registerBinding(n).catch(e => failures.set(n, e))),
|
|
400
|
+
);
|
|
401
|
+
try {
|
|
402
|
+
const r = await runSql(sql, rowLimit);
|
|
403
|
+
return { data: r.rows, fields: r.fields, truncated: r.truncated, rowCount: r.rowCount };
|
|
404
|
+
} catch (error) {
|
|
405
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
406
|
+
for (const [n, cause] of failures) {
|
|
407
|
+
if (message.includes(n)) throw cause;
|
|
408
|
+
}
|
|
409
|
+
if (failures.size) {
|
|
410
|
+
const details = [...failures.values()]
|
|
411
|
+
.map(e => (e instanceof Error ? e.message : String(e)))
|
|
412
|
+
.join("; ");
|
|
413
|
+
throw new Error(message + " (bindings that failed to load: " + details + ")");
|
|
414
|
+
}
|
|
415
|
+
throw error;
|
|
416
|
+
}
|
|
417
|
+
}, [sql, rowLimit], refreshing => refreshing.size > 0);
|
|
418
|
+
// A query over every binding refreshes every binding.
|
|
419
|
+
const refresh = React.useCallback(() => refreshBindings(), []);
|
|
420
|
+
return { ...state, refresh };
|
|
184
421
|
}
|
|
185
422
|
|
|
186
423
|
// ---------------------------------------------------------------------------
|
|
@@ -214,6 +451,21 @@ export function navigate(to, opts) {
|
|
|
214
451
|
window.history.pushState(null, "", url);
|
|
215
452
|
}
|
|
216
453
|
emitLocation();
|
|
454
|
+
// Inside Mako's shell the app is a sandboxed iframe with an opaque origin,
|
|
455
|
+
// so the line above moved a URL nobody can see or copy. Tell the host,
|
|
456
|
+
// which projects the query onto its own address bar (/apps/<slug>?...)
|
|
457
|
+
// and seeds it back into the iframe when that link is opened. Only the
|
|
458
|
+
// query travels: the frame's pathname is the preview token, not the app's.
|
|
459
|
+
if (window.parent !== window) {
|
|
460
|
+
try {
|
|
461
|
+
window.parent.postMessage(
|
|
462
|
+
{ type: "mako-app:navigate", search: url.search },
|
|
463
|
+
"*",
|
|
464
|
+
);
|
|
465
|
+
} catch {
|
|
466
|
+
// A host that is not Mako, or a frame that forbids it: nothing to tell.
|
|
467
|
+
}
|
|
468
|
+
}
|
|
217
469
|
}
|
|
218
470
|
|
|
219
471
|
export function useLocation() {
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@makoai/app-sdk",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.5.0",
|
|
4
4
|
"description": "Mako app SDK: data bindings (useQuery/useDuckDB), URL state, theme.",
|
|
5
|
-
"license": "
|
|
5
|
+
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "git+https://github.com/mako-ai/mako.git",
|
package/vite.d.ts
CHANGED
|
@@ -11,10 +11,30 @@ export interface MakoDataOptions {
|
|
|
11
11
|
slug?: string;
|
|
12
12
|
/** Repo root. Default: the nearest ancestor holding .mako/ or .git. */
|
|
13
13
|
repoRoot?: string;
|
|
14
|
-
/**
|
|
14
|
+
/**
|
|
15
|
+
* Re-fetch a cached parquet after this long (ms). Default: 5 minutes. A
|
|
16
|
+
* cache built from different binding text (or dbt environment) is never
|
|
17
|
+
* served, whatever this says — `Infinity` is safe while you edit SQL.
|
|
18
|
+
*/
|
|
15
19
|
revalidateMs?: number;
|
|
16
|
-
/**
|
|
20
|
+
/**
|
|
21
|
+
* Build bindings through the API: the local `bindings/<name>.sql` text
|
|
22
|
+
* (uncommitted edits included), or the committed binding when it was never
|
|
23
|
+
* materialized. `false` serves committed artifacts only. Default: true.
|
|
24
|
+
*/
|
|
17
25
|
materialize?: boolean;
|
|
26
|
+
/**
|
|
27
|
+
* Render `{{ dbt_schema }}` in dbt-linked bindings against this dbt
|
|
28
|
+
* environment (e.g. your personal one, `dbt_<you>`) instead of production.
|
|
29
|
+
* Those builds are yours alone — never stored as the app's data. Default:
|
|
30
|
+
* MAKO_DBT_ENV, else production.
|
|
31
|
+
*/
|
|
32
|
+
dbtEnvironment?: string;
|
|
33
|
+
/**
|
|
34
|
+
* Preview the app as this member (an email): `__data/viewer.json` answers
|
|
35
|
+
* as Mako would for them. Default: MAKO_VIEWER_AS, else yourself.
|
|
36
|
+
*/
|
|
37
|
+
viewAs?: string;
|
|
18
38
|
}
|
|
19
39
|
|
|
20
40
|
export interface MakoContext {
|
|
@@ -25,6 +45,10 @@ export interface MakoContext {
|
|
|
25
45
|
slug: string;
|
|
26
46
|
bindingsDir: string;
|
|
27
47
|
cacheDir: string;
|
|
48
|
+
/** Email of the member being previewed, or "" for yourself. */
|
|
49
|
+
viewAs: string;
|
|
50
|
+
/** dbt environment for `{{ dbt_schema }}`, or "" for production. */
|
|
51
|
+
dbtEnvironment: string;
|
|
28
52
|
}
|
|
29
53
|
|
|
30
54
|
/** Resolve credentials and identity the way `makoData` does. */
|
|
@@ -33,9 +57,18 @@ export function resolveMakoContext(
|
|
|
33
57
|
options?: MakoDataOptions,
|
|
34
58
|
): MakoContext;
|
|
35
59
|
|
|
60
|
+
/**
|
|
61
|
+
* What a cached parquet was built from: a hash of the binding file's text and
|
|
62
|
+
* the dbt environment. The plugin serves a cache entry only for a match.
|
|
63
|
+
*/
|
|
64
|
+
/** CRLF/CR → LF and no trailing whitespace — what bindingFingerprint hashes. */
|
|
65
|
+
export function normalizeBindingSource(source: string): string;
|
|
66
|
+
|
|
67
|
+
export function bindingFingerprint(source: string, dbtEnvironment?: string): string;
|
|
68
|
+
|
|
36
69
|
/**
|
|
37
70
|
* Serve the app's data bindings (`__data/index.json`, `__data/<name>.parquet`)
|
|
38
|
-
* during a local `vite dev
|
|
71
|
+
* during a local `vite dev`, built by Mako from the local binding files.
|
|
39
72
|
*/
|
|
40
73
|
export function makoData(options?: MakoDataOptions): Plugin;
|
|
41
74
|
export default makoData;
|
package/vite.js
CHANGED
|
@@ -4,13 +4,21 @@
|
|
|
4
4
|
// `__data/<name>.parquet` itself. On a laptop nothing does, so Vite's SPA
|
|
5
5
|
// fallback returns index.html and DuckDB fails with "footer != PAR1". This
|
|
6
6
|
// plugin is the laptop's answer: it lists the app's bindings/*.sql as
|
|
7
|
-
// __data/index.json and
|
|
8
|
-
//
|
|
7
|
+
// __data/index.json and serves each binding's parquet from the Mako API,
|
|
8
|
+
// authenticated with `mako login` or the workspace API key in the repo's .env.
|
|
9
|
+
//
|
|
10
|
+
// The LOCAL binding file is what gets built: its text goes to the API, which
|
|
11
|
+
// answers with the committed artifact when the text is the committed binding
|
|
12
|
+
// and with a throwaway draft build when it is not — so editing
|
|
13
|
+
// bindings/<name>.sql shows real data before anything is committed. The local
|
|
14
|
+
// cache is keyed by that text, so an edit never serves a parquet built from
|
|
15
|
+
// the old query.
|
|
9
16
|
//
|
|
10
17
|
// Plain ESM, Node built-ins only — like the rest of this package.
|
|
11
18
|
import fs from "node:fs";
|
|
12
19
|
import path from "node:path";
|
|
13
|
-
import {
|
|
20
|
+
import { createHash } from "node:crypto";
|
|
21
|
+
import { HOSTED_API_URL, findCredential, getAccessToken } from "./credentials.js";
|
|
14
22
|
|
|
15
23
|
const BINDING_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/;
|
|
16
24
|
const DEFAULT_REVALIDATE_MS = 5 * 60 * 1000;
|
|
@@ -72,23 +80,63 @@ export function resolveMakoContext(appDir, options = {}) {
|
|
|
72
80
|
const dotenv = readDotenv(path.join(repoRoot, ".env"));
|
|
73
81
|
const ws = readWorkspaceJson(repoRoot);
|
|
74
82
|
const env = (name) => process.env[name] ?? dotenv[name];
|
|
83
|
+
// Hosted Mako is the default: a fresh clone + `mako login` needs no .env.
|
|
84
|
+
// MAKO_API_URL / workspace.json apiUrl exist for self-hosted or local dev.
|
|
75
85
|
const apiUrl = (
|
|
76
86
|
options.apiUrl ??
|
|
77
87
|
env("MAKO_API_URL") ??
|
|
78
88
|
ws.apiUrl ??
|
|
79
|
-
|
|
89
|
+
HOSTED_API_URL
|
|
80
90
|
).replace(/\/+$/, "");
|
|
81
91
|
return {
|
|
82
92
|
repoRoot,
|
|
83
93
|
apiUrl,
|
|
84
94
|
apiKey: options.apiKey ?? env("MAKO_API_KEY") ?? "",
|
|
85
95
|
workspaceId: options.workspaceId ?? env("MAKO_WORKSPACE_ID") ?? ws.workspaceId ?? "",
|
|
86
|
-
|
|
96
|
+
// The manifest id is the app's identity (apps.md §29); the folder
|
|
97
|
+
// basename is only a fallback for apps that predate ids — and is
|
|
98
|
+
// ambiguous once apps nest.
|
|
99
|
+
slug: options.slug ?? readManifestId(appDir) ?? path.basename(path.resolve(appDir)),
|
|
87
100
|
bindingsDir: path.join(appDir, "bindings"),
|
|
88
101
|
cacheDir: path.join(appDir, "node_modules", ".mako-data"),
|
|
102
|
+
/** Preview the app as this viewer (email) — see makoData(). */
|
|
103
|
+
viewAs: options.viewAs ?? env("MAKO_VIEWER_AS") ?? "",
|
|
104
|
+
/** Render `{{ dbt_schema }}` against this dbt environment — see makoData(). */
|
|
105
|
+
dbtEnvironment: options.dbtEnvironment ?? env("MAKO_DBT_ENV") ?? "",
|
|
89
106
|
};
|
|
90
107
|
}
|
|
91
108
|
|
|
109
|
+
/** CRLF/CR → LF, no trailing whitespace at the end of the file. */
|
|
110
|
+
export function normalizeBindingSource(source) {
|
|
111
|
+
return source.replace(/\r\n?/g, "\n").trimEnd();
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* What a cached parquet was built from: the binding file's exact text plus
|
|
116
|
+
* the dbt environment it was rendered against. A cache entry is only ever
|
|
117
|
+
* served for the same fingerprint, whatever its age.
|
|
118
|
+
*/
|
|
119
|
+
export function bindingFingerprint(source, dbtEnvironment = "") {
|
|
120
|
+
// Line endings and trailing whitespace are not the query: a Windows
|
|
121
|
+
// checkout (core.autocrlf) must not look like an edit. The API normalises
|
|
122
|
+
// the text it compares the same way.
|
|
123
|
+
return createHash("sha256")
|
|
124
|
+
.update(normalizeBindingSource(source))
|
|
125
|
+
.update("\0")
|
|
126
|
+
.update(dbtEnvironment)
|
|
127
|
+
.digest("hex")
|
|
128
|
+
.slice(0, 32);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
function readManifestId(appDir) {
|
|
132
|
+
try {
|
|
133
|
+
const raw = JSON.parse(fs.readFileSync(path.join(appDir, "mako.json"), "utf8"));
|
|
134
|
+
return typeof raw.id === "string" && /^[0-9a-f]{24}$/i.test(raw.id) ? raw.id : null;
|
|
135
|
+
} catch {
|
|
136
|
+
return null;
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
92
140
|
function listBindings(bindingsDir) {
|
|
93
141
|
try {
|
|
94
142
|
return fs
|
|
@@ -122,8 +170,11 @@ export function makoData(options = {}) {
|
|
|
122
170
|
// once keeps working without ever pasting a key.
|
|
123
171
|
const loggedIn = !ctx.apiKey && !!findCredential(ctx.apiUrl, ctx.workspaceId);
|
|
124
172
|
const problems = [];
|
|
125
|
-
if (!ctx.apiUrl) problems.push("MAKO_API_URL is
|
|
126
|
-
if (!ctx.apiKey && !loggedIn)
|
|
173
|
+
if (!ctx.apiUrl) problems.push("MAKO_API_URL is set but empty");
|
|
174
|
+
if (!ctx.apiKey && !loggedIn)
|
|
175
|
+
problems.push(
|
|
176
|
+
`not signed in to ${ctx.apiUrl || "Mako"}: run \`npx @makoai/cli login\` in this repo (or set MAKO_API_KEY in .env)`,
|
|
177
|
+
);
|
|
127
178
|
if (!ctx.workspaceId) problems.push("workspace id unknown (.mako/workspace.json or MAKO_WORKSPACE_ID)");
|
|
128
179
|
const appBase = () =>
|
|
129
180
|
`${ctx.apiUrl}/api/workspaces/${encodeURIComponent(ctx.workspaceId)}/apps/${encodeURIComponent(ctx.slug)}`;
|
|
@@ -135,15 +186,32 @@ export function makoData(options = {}) {
|
|
|
135
186
|
` mako-data: ${bindings.length} binding(s) for apps/${ctx.slug}` +
|
|
136
187
|
(problems.length
|
|
137
188
|
? ` — NOT CONNECTED: ${problems.join("; ")} (see CLAUDE.md → Credentials)`
|
|
138
|
-
: ` via ${ctx.apiUrl} (${ctx.apiKey ? "API key" : "mako login"})`
|
|
189
|
+
: ` via ${ctx.apiUrl} (${ctx.apiKey ? "API key" : "mako login"})` +
|
|
190
|
+
(ctx.dbtEnvironment ? `, dbt environment "${ctx.dbtEnvironment}"` : "")),
|
|
139
191
|
);
|
|
140
192
|
|
|
193
|
+
// fetch() with network failures translated into something a person can
|
|
194
|
+
// act on — "fetch failed" alone has sent people debugging the wrong end.
|
|
195
|
+
async function apiFetch(url, init) {
|
|
196
|
+
try {
|
|
197
|
+
return await fetch(url, init);
|
|
198
|
+
} catch (error) {
|
|
199
|
+
const cause = error?.cause?.code ?? error?.cause?.message ?? error?.message ?? String(error);
|
|
200
|
+
throw new Error(
|
|
201
|
+
`cannot reach the Mako API at ${ctx.apiUrl} (${cause})` +
|
|
202
|
+
(ctx.apiUrl === HOSTED_API_URL
|
|
203
|
+
? " — check your network connection"
|
|
204
|
+
: ` — is that server running? Unset MAKO_API_URL (repo .env or environment) to use ${HOSTED_API_URL}`),
|
|
205
|
+
);
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
|
|
141
209
|
async function fetchArtifact(name) {
|
|
142
210
|
const url = `${appBase()}/bindings/${encodeURIComponent(name)}/artifact`;
|
|
143
|
-
let res = await
|
|
211
|
+
let res = await apiFetch(url, { headers: await headers() });
|
|
144
212
|
if (res.status === 404 && options.materialize !== false) {
|
|
145
213
|
// Never materialized (or a live binding): build it now, then read.
|
|
146
|
-
const built = await
|
|
214
|
+
const built = await apiFetch(
|
|
147
215
|
`${appBase()}/bindings/${encodeURIComponent(name)}/materialize`,
|
|
148
216
|
{ method: "POST", headers: await headers() },
|
|
149
217
|
);
|
|
@@ -151,43 +219,235 @@ export function makoData(options = {}) {
|
|
|
151
219
|
const text = await built.text().catch(() => "");
|
|
152
220
|
throw new Error(`materialize ${name}: HTTP ${built.status} ${text.slice(0, 300)}`);
|
|
153
221
|
}
|
|
154
|
-
res = await
|
|
222
|
+
res = await apiFetch(url, { headers: await headers() });
|
|
155
223
|
}
|
|
156
224
|
if (!res.ok) {
|
|
157
225
|
const text = await res.text().catch(() => "");
|
|
226
|
+
if (res.status === 401 || res.status === 403) {
|
|
227
|
+
throw new Error(
|
|
228
|
+
`the Mako API at ${ctx.apiUrl} refused the credential (HTTP ${res.status}) — ` +
|
|
229
|
+
(ctx.apiKey
|
|
230
|
+
? "the MAKO_API_KEY in .env is invalid for this host/workspace"
|
|
231
|
+
: "run `npx @makoai/cli login` in this repo again") +
|
|
232
|
+
(text ? ` (${text.slice(0, 200)})` : ""),
|
|
233
|
+
);
|
|
234
|
+
}
|
|
158
235
|
throw new Error(`artifact ${name}: HTTP ${res.status} ${text.slice(0, 300)}`);
|
|
159
236
|
}
|
|
160
237
|
return Buffer.from(await res.arrayBuffer());
|
|
161
238
|
}
|
|
162
239
|
|
|
240
|
+
// The local binding file, or null when the app has none by that name
|
|
241
|
+
// (then the committed binding is all there is to serve).
|
|
242
|
+
function readSource(name) {
|
|
243
|
+
try {
|
|
244
|
+
return fs.readFileSync(path.join(ctx.bindingsDir, `${name}.sql`), "utf8");
|
|
245
|
+
} catch {
|
|
246
|
+
return null;
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
const cachePath = (name) => path.join(ctx.cacheDir, `${name}.parquet`);
|
|
251
|
+
const metaPath = (name) => path.join(ctx.cacheDir, `${name}.parquet.json`);
|
|
252
|
+
|
|
253
|
+
function cachedFingerprint(name) {
|
|
254
|
+
try {
|
|
255
|
+
return JSON.parse(fs.readFileSync(metaPath(name), "utf8")).fingerprint ?? null;
|
|
256
|
+
} catch {
|
|
257
|
+
return null;
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
function writeCache(name, buf, meta) {
|
|
262
|
+
fs.mkdirSync(ctx.cacheDir, { recursive: true });
|
|
263
|
+
fs.writeFileSync(cachePath(name), buf);
|
|
264
|
+
if (meta) fs.writeFileSync(metaPath(name), JSON.stringify(meta));
|
|
265
|
+
else fs.rmSync(metaPath(name), { force: true });
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
// An API that predates dev builds answers the route with its not-found
|
|
269
|
+
// handler (`{"success":false,"error":"Not Found"}`, or plain text from
|
|
270
|
+
// a proxy) — or, for a `mako login` token or scoped key, with the
|
|
271
|
+
// scoped-credential refusal, since the route is not on its allowlist
|
|
272
|
+
// yet. Remembered, so the rest of the session asks for the committed
|
|
273
|
+
// artifact directly (the behaviour before dev builds existed). Any
|
|
274
|
+
// other 404 (no such app) falls back for that request only, so the
|
|
275
|
+
// artifact route reports it.
|
|
276
|
+
let devBuildUnsupported = false;
|
|
277
|
+
const inflight = new Map();
|
|
278
|
+
|
|
279
|
+
// Build the LOCAL binding text through the API. Concurrent asks for the
|
|
280
|
+
// same text share one request (a page mounting several tables at once).
|
|
281
|
+
function devBuild(name, source, refresh) {
|
|
282
|
+
const fingerprint = bindingFingerprint(source, ctx.dbtEnvironment);
|
|
283
|
+
const key = `${name}:${fingerprint}:${refresh ? 1 : 0}`;
|
|
284
|
+
let pending = inflight.get(key);
|
|
285
|
+
if (pending) return pending;
|
|
286
|
+
pending = (async () => {
|
|
287
|
+
const res = await apiFetch(`${appBase()}/bindings/${encodeURIComponent(name)}/dev-build`, {
|
|
288
|
+
method: "POST",
|
|
289
|
+
headers: { ...(await headers()), "content-type": "application/json" },
|
|
290
|
+
body: JSON.stringify({
|
|
291
|
+
source,
|
|
292
|
+
...(ctx.dbtEnvironment ? { dbtEnvironment: ctx.dbtEnvironment } : {}),
|
|
293
|
+
...(refresh ? { refresh: true } : {}),
|
|
294
|
+
}),
|
|
295
|
+
});
|
|
296
|
+
if (!res.ok) {
|
|
297
|
+
const text = await res.text().catch(() => "");
|
|
298
|
+
let body = null;
|
|
299
|
+
try {
|
|
300
|
+
body = JSON.parse(text);
|
|
301
|
+
} catch {
|
|
302
|
+
// Not the API's JSON error envelope.
|
|
303
|
+
}
|
|
304
|
+
const predatesDevBuild =
|
|
305
|
+
(res.status === 404 && (!body || body.error === "Not Found")) ||
|
|
306
|
+
(res.status === 403 && /restricted to the (\/api\/mcp|Mako MCP) endpoint/.test(body?.error ?? ""));
|
|
307
|
+
if (predatesDevBuild || res.status === 404) {
|
|
308
|
+
if (!predatesDevBuild) return null;
|
|
309
|
+
devBuildUnsupported = true;
|
|
310
|
+
server.config.logger.warn?.(
|
|
311
|
+
` mako-data: ${ctx.apiUrl} does not build local binding edits yet; serving committed bindings`,
|
|
312
|
+
);
|
|
313
|
+
return null;
|
|
314
|
+
}
|
|
315
|
+
const error = new Error(
|
|
316
|
+
res.status === 401
|
|
317
|
+
? `the Mako API at ${ctx.apiUrl} refused the credential (HTTP 401) — ` +
|
|
318
|
+
(ctx.apiKey
|
|
319
|
+
? "the MAKO_API_KEY in .env is invalid for this host/workspace"
|
|
320
|
+
: "run `npx @makoai/cli login` in this repo again")
|
|
321
|
+
: body?.error || `build ${name}: HTTP ${res.status}`,
|
|
322
|
+
);
|
|
323
|
+
error.status = res.status;
|
|
324
|
+
throw error;
|
|
325
|
+
}
|
|
326
|
+
const buf = Buffer.from(await res.arrayBuffer());
|
|
327
|
+
const meta = {
|
|
328
|
+
fingerprint,
|
|
329
|
+
dbtEnvironment: ctx.dbtEnvironment || null,
|
|
330
|
+
// A redirect to the stored artifact loses the API's headers; that
|
|
331
|
+
// answer is always the committed artifact.
|
|
332
|
+
build: res.headers.get("x-mako-build") ?? "artifact",
|
|
333
|
+
rowCount: Number(res.headers.get("x-mako-row-count") ?? "") || null,
|
|
334
|
+
builtAt: res.headers.get("x-mako-materialized-at") ?? new Date().toISOString(),
|
|
335
|
+
};
|
|
336
|
+
writeCache(name, buf, meta);
|
|
337
|
+
return { buf, meta };
|
|
338
|
+
})().finally(() => inflight.delete(key));
|
|
339
|
+
inflight.set(key, pending);
|
|
340
|
+
return pending;
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
// POST __data/<name>/refresh — the SDK's refresh(): rebuild the LOCAL
|
|
344
|
+
// binding through the API (the committed one is re-materialized and
|
|
345
|
+
// stored, an edited one is built as a draft), and cache what came back.
|
|
346
|
+
async function refreshBinding(name, res) {
|
|
347
|
+
const source = options.materialize === false || devBuildUnsupported ? null : readSource(name);
|
|
348
|
+
try {
|
|
349
|
+
const built = source === null ? null : await devBuild(name, source, true);
|
|
350
|
+
if (built) {
|
|
351
|
+
return json(res, 200, {
|
|
352
|
+
success: true,
|
|
353
|
+
binding: name,
|
|
354
|
+
materialization: "parquet",
|
|
355
|
+
rowCount: built.meta.rowCount ?? undefined,
|
|
356
|
+
byteSize: built.buf.length,
|
|
357
|
+
materializedAt: built.meta.builtAt,
|
|
358
|
+
});
|
|
359
|
+
}
|
|
360
|
+
const materialized = await apiFetch(
|
|
361
|
+
`${appBase()}/bindings/${encodeURIComponent(name)}/materialize`,
|
|
362
|
+
{ method: "POST", headers: await headers() },
|
|
363
|
+
);
|
|
364
|
+
const body = await materialized.json().catch(() => ({}));
|
|
365
|
+
if (!materialized.ok) {
|
|
366
|
+
return json(res, materialized.status, {
|
|
367
|
+
success: false,
|
|
368
|
+
error: body.error || `materialize ${name}: HTTP ${materialized.status}`,
|
|
369
|
+
});
|
|
370
|
+
}
|
|
371
|
+
fs.rmSync(cachePath(name), { force: true });
|
|
372
|
+
json(res, 200, {
|
|
373
|
+
success: true,
|
|
374
|
+
binding: name,
|
|
375
|
+
materialization: "parquet",
|
|
376
|
+
rowCount: body.rowCount,
|
|
377
|
+
byteSize: body.byteSize,
|
|
378
|
+
materializedAt: body.materializedAt,
|
|
379
|
+
});
|
|
380
|
+
} catch (error) {
|
|
381
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
382
|
+
server.config.logger.error(` mako-data: ${message}`);
|
|
383
|
+
json(res, error?.status ?? 502, { success: false, error: message });
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
// `__data/viewer.json` — the SDK's useViewer(): the developer's own
|
|
388
|
+
// identity, or, with MAKO_VIEWER_AS=<email> (env or .env), another
|
|
389
|
+
// member's, exactly as Mako would answer for them.
|
|
390
|
+
const viewAsQuery = ctx.viewAs ? `?as=${encodeURIComponent(ctx.viewAs)}` : "";
|
|
391
|
+
async function serveViewer(res) {
|
|
392
|
+
if (problems.length) return json(res, 200, null);
|
|
393
|
+
try {
|
|
394
|
+
const r = await apiFetch(`${appBase()}/viewer${viewAsQuery}`, {
|
|
395
|
+
headers: await headers(),
|
|
396
|
+
});
|
|
397
|
+
const body = await r.json().catch(() => ({}));
|
|
398
|
+
if (r.status === 404) return json(res, 200, null);
|
|
399
|
+
if (!r.ok) return json(res, r.status, { error: body.error ?? `viewer: HTTP ${r.status}` });
|
|
400
|
+
return json(res, 200, body.viewer ?? null);
|
|
401
|
+
} catch (error) {
|
|
402
|
+
return json(res, 502, { error: error instanceof Error ? error.message : String(error) });
|
|
403
|
+
}
|
|
404
|
+
}
|
|
405
|
+
|
|
163
406
|
server.middlewares.use(async (req, res, next) => {
|
|
164
407
|
const [pathname, query = ""] = (req.url || "").split("?");
|
|
165
408
|
if (pathname === "/__data/index.json") {
|
|
166
409
|
return json(res, 200, listBindings(ctx.bindingsDir));
|
|
167
410
|
}
|
|
168
|
-
|
|
411
|
+
if (pathname === "/__data/viewer.json") return serveViewer(res);
|
|
412
|
+
const match = /^\/__data\/([^/]+)(\.parquet|\/refresh)$/.exec(pathname);
|
|
169
413
|
if (!match) return next();
|
|
170
414
|
const name = decodeURIComponent(match[1]);
|
|
415
|
+
const isRefresh = match[2] === "/refresh";
|
|
171
416
|
if (!BINDING_NAME.test(name)) return json(res, 400, { error: "invalid binding name" });
|
|
417
|
+
if (isRefresh && req.method !== "POST") {
|
|
418
|
+
return json(res, 405, { error: "POST to refresh a binding" });
|
|
419
|
+
}
|
|
172
420
|
if (problems.length) {
|
|
173
421
|
return json(res, 503, {
|
|
174
422
|
error: `mako-data is not connected: ${problems.join("; ")}`,
|
|
175
423
|
hint: "Run `mako login` in this repo, or put MAKO_API_URL and MAKO_API_KEY in the repo's .env (see AGENTS.md).",
|
|
176
424
|
});
|
|
177
425
|
}
|
|
178
|
-
|
|
426
|
+
if (isRefresh) return refreshBinding(name, res);
|
|
427
|
+
const cached = cachePath(name);
|
|
179
428
|
const refresh = /(^|&)refresh(=|&|$)/.test(query);
|
|
429
|
+
const source = options.materialize === false || devBuildUnsupported ? null : readSource(name);
|
|
430
|
+
// Null without a local file: the committed artifact, cached by age alone.
|
|
431
|
+
const fingerprint = source === null ? null : bindingFingerprint(source, ctx.dbtEnvironment);
|
|
432
|
+
// A cache built from other text (or another dbt environment) is not
|
|
433
|
+
// this binding's data, however fresh — serving it is how an edited
|
|
434
|
+
// query ended up read with the old query's columns.
|
|
435
|
+
const cacheMatches = () => fingerprint === null || cachedFingerprint(name) === fingerprint;
|
|
436
|
+
const serveCached = (how) => {
|
|
437
|
+
res.setHeader("content-type", "application/vnd.apache.parquet");
|
|
438
|
+
res.setHeader("x-mako-data", how);
|
|
439
|
+
return fs.createReadStream(cached).pipe(res);
|
|
440
|
+
};
|
|
180
441
|
try {
|
|
181
442
|
const stat = fs.statSync(cached, { throwIfNoEntry: false });
|
|
182
443
|
const fresh = stat && Date.now() - stat.mtimeMs < revalidateMs;
|
|
183
|
-
if (!refresh && fresh)
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
444
|
+
if (!refresh && fresh && cacheMatches()) return serveCached("cache");
|
|
445
|
+
let buf = null;
|
|
446
|
+
if (source !== null) buf = (await devBuild(name, source, false))?.buf ?? null;
|
|
447
|
+
if (!buf) {
|
|
448
|
+
buf = await fetchArtifact(name);
|
|
449
|
+
writeCache(name, buf, null);
|
|
187
450
|
}
|
|
188
|
-
const buf = await fetchArtifact(name);
|
|
189
|
-
fs.mkdirSync(ctx.cacheDir, { recursive: true });
|
|
190
|
-
fs.writeFileSync(cached, buf);
|
|
191
451
|
res.setHeader("content-type", "application/vnd.apache.parquet");
|
|
192
452
|
res.setHeader("content-length", String(buf.length));
|
|
193
453
|
res.setHeader("x-mako-data", "api");
|
|
@@ -195,13 +455,10 @@ export function makoData(options = {}) {
|
|
|
195
455
|
} catch (error) {
|
|
196
456
|
const message = error instanceof Error ? error.message : String(error);
|
|
197
457
|
server.config.logger.error(` mako-data: ${message}`);
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
return fs.createReadStream(cached).pipe(res);
|
|
203
|
-
}
|
|
204
|
-
json(res, 502, { error: message });
|
|
458
|
+
// Stale beats nothing while offline — but only data built from THIS
|
|
459
|
+
// text; an old query's parquet is not a stale copy of a new one.
|
|
460
|
+
if (fs.existsSync(cached) && cacheMatches()) return serveCached("stale");
|
|
461
|
+
json(res, error?.status ?? 502, { error: message });
|
|
205
462
|
}
|
|
206
463
|
});
|
|
207
464
|
},
|