@synthigy/sdk 0.1.2 → 0.2.1

package/README.md

@@ -13,20 +13,17 @@ npm install @synthigy/sdk
 ```ts
 import { createClient } from '@synthigy/sdk'
 
-const synthigy = createClient({
-  endpoint:     'http://localhost:7887',
-  clientId:     process.env.SYNTHIGY_CLIENT_ID,
-  clientSecret: process.env.SYNTHIGY_CLIENT_SECRET,
-  // The audience model is opt-in: a token naming none is identity-only and
-  // /data rejects it. Your server publishes this at /.well-known/synthigy
-  // (auth.oidc.audience). Defaults to $SYNTHIGY_AUDIENCE on Node. See docs/AUTH.md.
-  audience:     'https://synthigy.com',
-})
-
-// Read — you get back exactly the shape you ask for
-const movies = await synthigy.search('Movie',
-  { _limit: 5, _order_by: [['release_year', 'desc']] },
-  { title: null, release_year: null, genres: { name: null } })
+// Endpoint and identity come from `synthigy exec` (see Code generation, step 3).
+const synthigy = createClient()
+
+// Read — XSQL: the shape you write is the shape you get back
+const movies = await synthigy.query(`
+movie (limit 5, order by release_year desc)
+  xid
+  title
+  release_year
+  ->genres
+    name`)
 
 // Write — additive; doesn't disturb the movie's other ratings
 await synthigy.stack('user_rating', {
@@ -43,11 +40,12 @@ for await (const ev of w.events) {
 }
 ```
 
+Run it with `synthigy exec -- node hello.ts`.
+
 ## What makes it Synthigy
 
 - **The query *is* the result shape.** Ask for fields and relations; get back
-  that JSON and nothing else. Two surfaces for the same engine: an
-  [XSQL](./docs/XSQL.md) string, or a [wire](./docs/WIRE-FORMAT.md) selection object.
+  that JSON and nothing else, written in [XSQL](./docs/XSQL.md).
 
 - **Writes are silent by default.** `sync`/`stack` answer `{ count }`, not the
   record. Mint the id up front with `newXid()` when you need it — cheaper than
@@ -55,29 +53,119 @@ for await (const ev of w.events) {
   Pass `{ returning: true }` for the record; generated code types the two apart.
 - **Writes that ORMs make you hand-roll.** `stack` adds a child without
   clobbering its siblings; `slice` detaches a link without deleting the record.
-  Plus `sync` (upsert), `delete`, `purge`. → [WIRE-FORMAT.md](./docs/WIRE-FORMAT.md)
+  Plus `sync` (upsert), `delete`, `purge`.
 
 - **Live data on one connection.** Open dozens of watches — they multiplex onto
   a single SSE per client. `watchQuery` for a live result set,
   `watchSqlTemplate` for live analytics, `watch` for raw record events.
-  → [WATCH.md](./docs/WATCH.md)
 
 - **`actingAs` per call.** Every read and write can run as a specific user, with
   IAM / RBAC / row-level security enforced *server-side*. Tokens never have to
-  reach the browser. → [AUTH.md](./docs/AUTH.md)
+  reach the browser. `client.login` runs the OIDC authorization-code + PKCE
+  exchange for your BFF and leaves sessions to you; `createBrowserLogin` does
+  the same for a browser app, as a public client with silent renew and tokens
+  in memory.
 
-- **Typed from your model.** `synthigy-gen` (needs `typescript` in your project) compiles your ERD + `.xsql` files
+- **Typed from your model.** `synthigy-gen` compiles your ERD + `.xsql` files
   into typed methods whose result types follow the selection — a typo'd entity
-  or an unselected field is a compile error. → [codegen](./docs/WATCH.md#codegen)
+  or an unselected field is a compile error. With `typescript` (any version, 7
+  included) in your project the generated files are type-checked before they
+  are written. → [Code generation](#code-generation)
+
+## Code generation
+
+Write your queries in `.xsql` files and get typed functions for them. The
+server compiles the queries, so the types always match what it returns.
+
+**1. Get a server.** In your project folder:
+
+```bash
+synthigy env init
+synthigy up
+```
+
+The first `up` prints a `/setup` link; open it and pick a database. (No
+browser? `synthigy up --db sqlite` skips the wizard.) Already have a server?
+Skip this step.
+
+**2. Deploy your data model** in the modeler (or from code with `client.deploy()`, as a
+client with the Dataset Developer role).
+
+**3. Connect as your app.** Create its client once, then save it to the
+project:
+
+```bash
+synthigy iam add-client "My App" --id my-app --type confidential \
+  --role "Dataset Explorer" --api Synthigy --grant client_credentials --local
+synthigy connect http://localhost:7887 --client-id my-app
+```
+
+`add-client` prints the secret once; `connect` asks for it. Code is generated
+for what this app is allowed to see. (`--local` works on the server's own
+machine; for a remote server, create the client in the console.)
+
+**4. Install the SDK:**
+
+```bash
+npm install @synthigy/sdk
+npm install -D typescript   # optional: type-checks the generated files
+```
+
+**5. Write a query** in `xsql/movies.xsql`:
+
+```
+@search list
+movie (release_year > ?since:int=1990, limit ?limit:int=20)
+  xid
+  title
+  release_year
+```
+
+**6. Generate:**
+
+```bash
+synthigy exec -- npx synthigy-gen xsql/ generated/
+```
+
+This writes `generated/ops.ts` and `generated/schema.ts`, and saves `xsql/schema.json` and `xsql/ops.ir.json`
+next to your queries.
+
+**7. Use it:**
+
+```ts
+import { configure, Movie } from './generated/ops.ts'
+
+configure()
+const movies = await Movie.list({ since: 2000 })
+console.log(movies.map(m => m.title))
+```
+
+```bash
+synthigy exec -- node app.ts
+```
+
+`synthigy exec` gives your program the server address and the app's identity (Node 23+ runs `.ts` directly; set `"type": "module"` in `package.json`).
+Without it, pass them yourself: `configure({ endpoint, clientId, clientSecret })`.
+
+**After you edit a query**, run step 6 again. As long as the `.xsql` files are
+unchanged it works offline from `xsql/ops.ir.json`; after an edit it needs the
+server, and it never generates from outdated results. In CI:
+
+```bash
+npx synthigy-gen check xsql/
+```
+
+**What to commit:** your `.xsql` files and `xsql/ops.ir.json`.
+`xsql/schema.json` is your whole data model, so commit it only in a private
+repo.
+
+`@watch` ops also get a live `watch<Name>()` method, `@batch` ops become one exported function that sends every member in one request (a failed member is a `SynthigyError` in its slot), and every entity gets typed `sync` / `stack` / `delete`.
 
 ## Docs
 
 | Doc | What's in it |
 |---|---|
 | [XSQL.md](./docs/XSQL.md) | The query language: shapes, params, aggregates, op files, sql-templates |
-| [WIRE-FORMAT.md](./docs/WIRE-FORMAT.md) | JSON selections, args/operators, result conventions, the five write primitives |
-| [WATCH.md](./docs/WATCH.md) | `watch` / `watchQuery` / `watchSqlTemplate` / `observe`, lifecycle, and codegen |
-| [AUTH.md](./docs/AUTH.md) | OAuth client registration, `actingAs`, BFF / SPA / native patterns |
 | [CHANGELOG.md](./CHANGELOG.md) | Version history |
 | [synthigy/examples: movies/js](https://github.com/synthigy/examples/tree/main/movies/js) | End-to-end Datastar BFF against the published package |
 | [src/index.d.ts](./src/index.d.ts) | Full type definitions |

package/codegen/codegen.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Unified codegen tool:
-//   node codegen.mjs <file.xsql> [outDir]   — describe + gen TS (saves .ir.json)
-//   node codegen.mjs check <file.xsql>       — re-describe, diff, exit 1 on drift
+//   node codegen.mjs <xsql...> [outDir]     — describe + gen TS (saves ops.ir.json)
+//   node codegen.mjs check <xsql...>         — re-describe, diff, exit 1 on drift
 //   node codegen.mjs pull [endpoint] [out]   — pull schema.json (wraps pull.mjs)
 //
 // Config via env: SYNTHIGY_ENDPOINT, SYNTHIGY_CLIENT_ID, SYNTHIGY_CLIENT_SECRET
@@ -11,32 +11,16 @@ import path from 'node:path'
 import { createHash } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
 import { createRequire } from 'node:module'
-import { TS, tsScalar, pascal, camel } from './lib.mjs'
+import { TS, tsScalar, pascal, camel, warnStaleSchema } from './lib.mjs'
 import { PLATFORM_AUDIENCE } from '../src/index.js'
 
-// typescript is an optional peer: the runtime client has no dependencies and
-// must stay that way, but generating .ts files needs the compiler — resolved
-// from the consumer's project, where a TypeScript codebase already has it.
-let ts
+let tsVersion = null
 try {
-  ts = createRequire(import.meta.url)('typescript')
-} catch {
-  console.error('synthigy-gen: `typescript` is required to generate code and was not found.\n' +
-                '  npm install -D typescript')
-  process.exit(1)
-}
+  tsVersion = createRequire(import.meta.url)('typescript/package.json').version
+} catch {}
 
 const here = path.dirname(new URL(import.meta.url).pathname)
 
-// Reformat generated TS through the compiler's own printer: correct indentation,
-// spacing and semicolons with zero hand-managed `\n`. The printer round-trips the
-// AST, so it fixes structural formatting while preserving embedded XSQL template
-// literals verbatim. (Realizes the "AST emission" goal cheaply; the fail-loud tsc
-// gate below still validates the result.)
-const formatTs = (code, file) =>
-  ts.createPrinter({ newLine: ts.NewLineKind.LineFeed })
-    .printFile(ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true))
-
 // ── args + flags ──────────────────────────────────────────────────────────────
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(`
@@ -54,7 +38,7 @@ Flags:
   --schema <path>      explicit schema.json path (skips auto-pull)
 
 Environment:
-  SYNTHIGY_ENDPOINT        server URL (default: http://localhost:7887)
+  SYNTHIGY_ENDPOINT        server URL (required when a server is needed)
   SYNTHIGY_CLIENT_ID       OAuth client ID
   SYNTHIGY_CLIENT_SECRET   OAuth client secret
   SYNTHIGY_AUDIENCE        client_credentials audience, when the server requires one
@@ -99,13 +83,13 @@ if (pullMode) {
 // is input. check mode has no outDir — every positional is input.
 const rawPos  = checkMode ? pos.slice(1) : pos
 const lastPos = rawPos[rawPos.length - 1]
-const hasExplicitOut = !checkMode && lastPos && !lastPos.endsWith('.xsql')
+const hasExplicitOut = !checkMode && rawPos.length > 1 && !lastPos.endsWith('.xsql')
 const outArg  = hasExplicitOut ? lastPos : undefined
 const xsqlArgs = hasExplicitOut ? rawPos.slice(0, -1) : rawPos
 
 if (!xsqlArgs.length) {
-  console.error('usage: node codegen.mjs [flags] <file.xsql> [file2.xsql ...] [outDir]')
-  console.error('       node codegen.mjs check <file.xsql> [file2.xsql ...]')
+  console.error('usage: node codegen.mjs [flags] <file.xsql|dir> [...] [outDir]   (dirs searched recursively)')
+  console.error('       node codegen.mjs check <file.xsql|dir> [...]')
   console.error('       node codegen.mjs pull [endpoint] [schema.json]')
   console.error('flags: --pull                force schema refresh')
   console.error('       --keys snake|camel    field casing (default: snake)')
@@ -114,14 +98,20 @@ if (!xsqlArgs.length) {
   process.exit(1)
 }
 
+const isDir = p => fs.existsSync(p) && fs.statSync(p).isDirectory()
 const xsqlPaths = xsqlArgs.flatMap(a => {
   const p = path.resolve(a)
-  if (fs.existsSync(p) && fs.statSync(p).isDirectory())
-    return fs.readdirSync(p).filter(f => f.endsWith('.xsql')).sort().map(f => path.join(p, f))
+  if (isDir(p))
+    return fs.readdirSync(p, { recursive: true })
+      .map(f => f.split(path.sep).join('/'))
+      .filter(f => f.endsWith('.xsql') && fs.statSync(path.join(p, f)).isFile())
+      .sort()
+      .map(f => path.join(p, f))
   return [p]
 })
 if (!xsqlPaths.length) { console.error('no .xsql files found'); process.exit(1) }
-const xsqlDir   = path.dirname(xsqlPaths[0])   // schema.json lives next to first file
+const firstArg  = path.resolve(xsqlArgs[0])
+const xsqlDir   = isDir(firstArg) ? firstArg : path.dirname(firstArg)   // IR + schema.json home
 const irPath    = path.join(xsqlDir, 'ops.ir.json')
 const outDir    = checkMode
   ? null
@@ -137,14 +127,21 @@ const schemaPath = flags.schemaOverride ?? localSchemaPath
 const toKey = flags.keys === 'camel' ? camel : s => s
 
 // ── describe ─────────────────────────────────────────────────────────────────
-const ENDPOINT = process.env.SYNTHIGY_ENDPOINT ?? 'http://localhost:7887'
+const ENDPOINT = process.env.SYNTHIGY_ENDPOINT
+function endpoint() {
+  if (ENDPOINT) return ENDPOINT
+  console.error('NO_ENDPOINT: no endpoint — set SYNTHIGY_ENDPOINT (run under `synthigy exec`)')
+  process.exit(1)
+}
 const { SYNTHIGY_CLIENT_ID, SYNTHIGY_CLIENT_SECRET, SYNTHIGY_AUDIENCE } = process.env
 
 // Auto-pull schema if missing or --pull requested (saved next to .xsql, cached for future runs).
 if (!flags.schemaOverride && (flags.pull || !fs.existsSync(schemaPath))) {
   execFileSync(process.execPath,
-    [path.join(here, 'pull.mjs'), ENDPOINT, schemaPath],
+    [path.join(here, 'pull.mjs'), endpoint(), schemaPath],
     { stdio: 'inherit', env: process.env })
+} else {
+  await warnStaleSchema(ENDPOINT, schemaPath)
 }
 
 if (!fs.existsSync(schemaPath)) {
@@ -154,7 +151,7 @@ if (!fs.existsSync(schemaPath)) {
 
 async function token() {
   if (!SYNTHIGY_CLIENT_ID) return ''
-  const r = await fetch(`${ENDPOINT}/oauth/token`, {
+  const r = await fetch(`${endpoint()}/oauth/token`, {
     method: 'POST',
     headers: { 'content-type': 'application/x-www-form-urlencoded' },
     body: new URLSearchParams({ grant_type: 'client_credentials',
@@ -169,21 +166,37 @@ async function token() {
 }
 
 // Merge all xsql files — ops are independent, names must be unique across files.
-const source = xsqlPaths.map(p => fs.readFileSync(p, 'utf8')).join('\n\n')
+// `@workspace` is buffer-scoped and must precede the first op, so only the
+// first file's survives the merge — left in place it lands INSIDE the
+// preceding file's last op and the server rejects that op at run time.
+const dropWorkspace = (src) => src.split('\n').filter(l => !/^@workspace\b/.test(l)).join('\n')
+const source = xsqlPaths
+  .map((p, i) => { const src = fs.readFileSync(p, 'utf8'); return i === 0 ? src : dropWorkspace(src) })
+  .join('\n\n')
+// describe parses each file on its own — concatenated, file 1's buffer
+// @namespace would leak into every later file and theirs would be dropped.
+const sources = xsqlPaths.map(p => ({
+  path: path.relative(xsqlDir, p).split(path.sep).join('/'),
+  source: fs.readFileSync(p, 'utf8'),
+}))
 // Contract between the .xsql sources on disk and the saved IR: the IR carries
 // the hash of the sources it was described from. Mismatch = the IR is stale.
 const sourceHash = createHash('sha256').update(source).digest('hex')
 
 // check mode fails FAST and OFFLINE when the sources drifted from the saved IR —
 // no backend/credentials needed to catch "edited .xsql, forgot codegen".
-// (A hash match still goes through the live describe-diff below: same sources
-// can yield a different IR after a server-side model change.)
+// A hash match still goes through the live describe-diff below when a server is
+// configured: same sources can yield a different IR after a model change.
 if (checkMode && fs.existsSync(irPath)) {
   const saved = JSON.parse(fs.readFileSync(irPath, 'utf8'))
   if (saved.sourceHash && saved.sourceHash !== sourceHash) {
-    console.error(`sources drifted from saved IR — run: node codegen.mjs ${xsqlArgs.join(' ')}`)
+    console.error(`sources drifted from saved IR — run: synthigy-gen ${xsqlArgs.join(' ')}`)
     process.exit(1)
   }
+  if (saved.sourceHash && !['SYNTHIGY_ENDPOINT', 'SYNTHIGY_TOKEN', 'SYNTHIGY_CLIENT_ID'].some(k => process.env[k])) {
+    console.log('ok — sourceHash matches saved IR (offline; set SYNTHIGY_* env for a live describe-diff)')
+    process.exit(0)
+  }
 }
 
 // Describe: use the cached IR only when it matches the sources on disk
@@ -200,14 +213,12 @@ if (cached && cached.sourceHash === sourceHash) {
     console.log(cached.sourceHash
       ? 'sources changed since IR pull — refreshing'
       : 'saved IR predates source hashing — refreshing')
-  // The canonical parser owns @namespace/@watch/@returns now — send source as-is.
-  const sourceForDescribe = source
   try {
     const tok = await token()
-    const resp = await fetch(`${ENDPOINT}/data`, {
+    const resp = await fetch(`${endpoint()}/data`, {
       method: 'POST',
       headers: { 'content-type': 'application/json', ...(tok && { authorization: `Bearer ${tok}` }) },
-      body: JSON.stringify({ operations: [{ op: 'describe', source: sourceForDescribe }] }),
+      body: JSON.stringify({ operations: [{ op: 'describe', sources }] }),
     })
     if (!resp.ok) throw new Error(`describe ${resp.status}: ${await resp.text()}`)
     const body = await resp.json()
@@ -223,7 +234,7 @@ if (cached && cached.sourceHash === sourceHash) {
       throw new Error(`describe returned no operations: ${JSON.stringify(ir).slice(0, 200)}`)
   } catch (e) {
     console.error(cached
-      ? `sources changed since IR pull and describe failed (${e.message}) — start a backend (SYNTHIGY_ENDPOINT) or revert the .xsql edit`
+      ? `sources changed since IR pull and describe failed (${e.message}) — run under \`synthigy exec\` or revert the .xsql edit`
       : `describe failed: ${e.message}`)
     process.exit(1)
   }
@@ -275,7 +286,7 @@ const sdkSrc  = sdkRoot.includes(`${path.sep}node_modules${path.sep}`)
 const ent     = (n) => schema.entities[n] ?? {}
 const visited = new Set()
 
-// The server owns pretty-name derivation (docs/plans/PLAN-SCHEMA-SKINS-PROJECTION.md):
+// The server owns pretty-name derivation:
 // entity/attribute/relation `skins` in the pulled schema are the contract, not a hint.
 // Falls back to the local splitter only for names with no schema entry (op/namespace
 // identifiers, which are snake-authored code with no display label to preserve).
@@ -360,13 +371,11 @@ for (const n of allEntities) nsOf(entityPascal(n))
 // Mutations are Layer-1 territory (schema-derived Entity.sync/stack/delete) —
 // never emitted from XSQL. Skip LOUDLY, never silently.
 const MUTATE_VERBS = new Set(['sync', 'stack', 'delete'])
+const genOps  = []   // generated reads, for @batch member resolution
+const batches = []
 for (const op of ir.operations) {
   if (op.batch) {
-    // The Python and PHP generators emit a batch function; this one does not
-    // yet. Say so — the author declared an operation and would otherwise get
-    // nothing back with no diagnostic.
-    console.warn(`skipped @batch ${op.name} — not generated by the JS codegen yet; ` +
-                 `call the members individually, or exec([op(...), op(...)]) for one round trip`)
+    batches.push(op)
     continue
   }
   if (MUTATE_VERBS.has(op.op)) {
@@ -391,6 +400,7 @@ for (const op of ir.operations) {
   const ret         = op.op === 'get' ? `Promise<${Type} | null>` : `Promise<${Type}[]>`
   const methodName  = camel(op.name)
 
+  genOps.push({ op, Type })
   if (ParamsT) g.typeAliases.push(`export type ${ParamsT} = {\n${pb}\n}`)
   g.typeAliases.push(`export type ${Type} = ${isSql ? plainResultType(op.result) : projectionType(op.entity, op.result.fields)}`)
   if (!isSql) g.typeAliases.push(`export const ${Type}Sel = ${JSON.stringify(fieldsToSel(op.result.fields), null, 2)} as const`)
@@ -407,6 +417,69 @@ for (const op of ir.operations) {
     : `  watch${pascal(methodName)}(${pArg}): QueryWatch<${Type}> {\n    return _client.watchQuery.xsql<${Type}>(${xsqlLiteral(`@${op.op} ${op.name}\n` + op.source)}, ${pPass}, { entity: ${JSON.stringify(op.entity)}, op: ${JSON.stringify(op.op)}, searchOpts: opts })\n  }`)
 }
 
+// @batch <name>: <m1> <m2> → one exported function, ONE exec round trip. Results
+// are keyed by member name (qualified ns/name when a bare name repeats); a failed
+// member is a SynthigyError VALUE in its slot, never a batch-wide throw. Params
+// are one flat object shared by every member — the Python generator's rules.
+const opIdentity = o => `${(o.namespace ?? o.entity ?? '').toLowerCase()}/${o.name.toLowerCase()}`
+function resolveMember(batchName, ref) {
+  const i  = ref.lastIndexOf('/')
+  const ns = i >= 0 ? ref.slice(0, i).toLowerCase() : null
+  const nm = ref.slice(i + 1).toLowerCase()
+  const matches = genOps.filter(({ op }) => op.name.toLowerCase() === nm &&
+    (ns === null || (op.namespace ?? op.entity ?? '').toLowerCase() === ns))
+  if (!matches.length)
+    throw new Error(`@batch ${batchName} references unknown/ungenerated op ${ref}`)
+  if (ns === null && matches.length > 1)
+    throw new Error(`@batch ${batchName} — ${ref} is ambiguous: ${matches.map(m => opIdentity(m.op)).join(', ')} — qualify the reference`)
+  return matches[0]
+}
+const batchChunks = []
+for (const b of batches) {
+  const members = b.members.map(ref => resolveMember(b.name, ref))
+  const merged = new Map()
+  for (const { op } of members)
+    for (const p of op.params ?? []) {
+      const seen = merged.get(p.name)
+      if (!seen) merged.set(p.name, { ...p })
+      else if (!p.optional) seen.optional = false
+    }
+  const params = [...merged.values()]
+  const names  = members.map(({ op }) => op.name.toLowerCase())
+  const key    = ({ op }) => names.filter(n => n === op.name.toLowerCase()).length > 1 ? opIdentity(op) : op.name
+  const fn     = camel(b.name)
+  const B      = pascal(b.name)
+  const pb     = paramsBody(params)
+  const allOpt = params.every(p => p.optional)
+  const lines  = []
+  if (pb) lines.push(`export type ${B}BatchParams = {\n${pb}\n}`)
+  lines.push(`export type ${B}Batch = {\n${members.map(m =>
+    `  ${JSON.stringify(key(m))}: ${m.op.op === 'get' ? `${m.Type} | null` : `${m.Type}[]`} | SynthigyError`).join('\n')}\n}`)
+  const ops = members.map(({ op }) => op.op === 'sql-template'
+    ? `    op.sqlTemplate(${xsqlLiteral(op.source)}, p),`
+    : `    op.query(${xsqlLiteral(`@${op.op} ${op.name}\n` + op.source)}, p, ${JSON.stringify(op.op)}),`)
+  const res = members.map((m, i) => `    ${JSON.stringify(key(m))}: _batchResult(r[${i}], ${JSON.stringify(m.op.op)}) as ${B}Batch[${JSON.stringify(key(m))}],`)
+  lines.push(`/**
+ * Batch: ${b.members.join(' + ')} — ONE request. Results are keyed by member; a
+ * failed member is a SynthigyError value in its slot, not a throw. Params are one
+ * object shared by every member.
+ */
+export async function ${fn}(${pb ? `params${allOpt ? '?' : ''}: ${B}BatchParams, ` : ''}opts?: ExecOpts): Promise<${B}Batch> {
+  const p = ${pb ? 'params ?? {}' : '{}'}
+  const r = await _client.exec([
+${ops.join('\n')}
+  ], opts)
+  return {
+${res.join('\n')}
+  }
+}`)
+  batchChunks.push(lines.join('\n\n'))
+}
+if (batchChunks.length) batchChunks.unshift(`function _batchResult(r: OperationResult, verb: string): unknown {
+  if (!r?.ok) return new SynthigyError(r?.error?.message ?? 'operation failed', r?.error?.code ?? 'OPERATION_FAILED')
+  return verb === 'get' ? (r.data ?? null) : (r.data ?? [])
+}`)
+
 // Emit one chunk per namespace: projection types + the object (reads + writes).
 const nsChunks = []
 for (const NS of Object.keys(nsMap).sort()) {
@@ -472,8 +545,8 @@ const aliasImports = allEntities.flatMap(n =>
 ).join(', ')
 const inputNames = xsqlPaths.map(p => path.basename(p)).join(', ')
 const OPS_HDR_COMMENT = `// AUTO-GENERATED from ${inputNames}. Do not edit.\n`
-const OPS_HDR_CODE = `import type { SynthigyClient, ClientConfig, ExecOpts, WriteOpts, QueryWatch, SqlTemplateWatch } from "${sdkSrc}"
-import { connect } from "${sdkSrc}"
+const OPS_HDR_CODE = `import type { SynthigyClient, ClientConfig, ExecOpts, WriteOpts, QueryWatch, SqlTemplateWatch${batchChunks.length ? ', OperationResult' : ''} } from "${sdkSrc}"
+import { connect${batchChunks.length ? ', op, SynthigyError' : ''} } from "${sdkSrc}"
 import type { ${aliasImports} } from "./schema.js"
 
 /** What a write answers by default — writes are silent unless \`returning\`. */
@@ -490,7 +563,7 @@ let _client: SynthigyClient
  * points every generated method at it. One process, one client, one token
  * cache, one SSE. Reconnect by calling again (destroys the previous client).
  */
-export function configure(config: ClientConfig): void {
+export function configure(config: ClientConfig = {}): void {
   _client = connect(${flags.keys === 'camel' ? '{ ...config, keyFormat: \'camel\' }' : 'config'})
 }
 
@@ -509,9 +582,8 @@ const _toSnake = (v: unknown): unknown => {
 const SCHEMA_HDR = `// AUTO-GENERATED — entity types from /schema ${schema.version ?? ''}. Do not edit.\n`
 
 fs.mkdirSync(outDir, { recursive: true })
-// The printer drops the detached top-of-file comment, so prepend it after formatting.
-fs.writeFileSync(path.join(outDir, 'schema.ts'), SCHEMA_HDR + formatTs(schemaChunks.join('\n\n'), 'schema.ts'))
-fs.writeFileSync(path.join(outDir, 'ops.ts'),    OPS_HDR_COMMENT + formatTs(OPS_HDR_CODE + nsChunks.join('\n\n'), 'ops.ts'))
+fs.writeFileSync(path.join(outDir, 'schema.ts'), SCHEMA_HDR + schemaChunks.join('\n\n') + '\n')
+fs.writeFileSync(path.join(outDir, 'ops.ts'),    OPS_HDR_COMMENT + OPS_HDR_CODE + [...nsChunks, ...batchChunks].join('\n\n') + '\n')
 
 // Gate, not a builder: VALIDATE the generated TS and FAIL LOUD if it doesn't
 // type-check — never ship broken/stale output silently (the old emit-and-swallow
@@ -536,7 +608,7 @@ const tscBin = (() => {
 
 // `--ignoreConfig` needs TypeScript 6. On 5.x the flag is itself an error, and
 // naming files explicitly already makes tsc skip tsconfig.json, so it is left off.
-const tscMajor = Number.parseInt(ts.version ?? '0', 10) || 0
+const tscMajor = Number.parseInt(tsVersion ?? '0', 10) || 0
 if (tscBin) {
   try {
     execFileSync(tscBin, [
@@ -552,9 +624,9 @@ if (tscBin) {
     process.exit(1)
   }
 } else {
-  process.stderr.write('codegen: tsc not found — skipping the type-check gate.\n')
+  process.stderr.write('codegen: tsc not found — skipping the type-check gate (npm install -D typescript).\n')
 }
 const flagSummary = [flags.keys !== 'snake' && `keys=${flags.keys}`, !flags.writes && 'no-writes'].filter(Boolean).join(' ')
 const opCount = ir.operations.filter(o => !o.batch).length
 const inputSummary = xsqlPaths.map(p => path.basename(p)).join(' + ')
-console.log(`${inputSummary} → ${allEntities.length} entities (full model), ${Object.keys(nsMap).length} namespaces, ${opCount} ops${flagSummary ? ` [${flagSummary}]` : ''} → ${outDir}`)
+console.log(`${inputSummary} → ${allEntities.length} entities (full model), ${Object.keys(nsMap).length} namespaces, ${opCount} ops${batches.length ? `, ${batches.length} batches` : ''}${flagSummary ? ` [${flagSummary}]` : ''} → ${outDir}`)

package/codegen/lib.mjs

@@ -1,3 +1,5 @@
+import fs from 'node:fs'
+
 // Shared codegen primitives for the TS emitters — one home for the scalar-type
 // map + casing so the read and write emitters can't drift apart.
 
@@ -28,3 +30,25 @@ export const camel = (s) => { const p = pascal(s); return p[0].toLowerCase() + p
 export const snake = (s) => words(s).join('_')
 // kebab wire keys aren't valid TS identifiers → keep verbatim, quote when needed.
 export const tsKey = (k) => (/^[A-Za-z_$][\w$]*$/.test(k) ? k : JSON.stringify(k))
+
+// One line on `write` when the schema's deploy stamp is older than the model at
+// /.well-known/synthigy. Silent on any failure: generation stays offline-capable.
+export async function warnStaleSchema(endpoint, schemaPath, write = (s) => console.error(s)) {
+  if (!endpoint || !fs.existsSync(schemaPath)) return
+  let local, remote
+  try {
+    local = JSON.parse(fs.readFileSync(schemaPath, 'utf8')).datasets ?? {}
+    const r = await fetch(`${endpoint.replace(/\/$/, '')}/.well-known/synthigy`,
+      { signal: AbortSignal.timeout(2000) })
+    if (!r.ok) return
+    remote = (await r.json()).datasets ?? {}
+  } catch {
+    return
+  }
+  const instant = (s) => (Number.isNaN(Date.parse(s)) ? s : Date.parse(s))
+  const changed = Object.keys(remote).filter((id) => instant(local[id]?.['deployed-at']) !== instant(remote[id]))
+    .concat(Object.keys(local).filter((id) => !(id in remote)))
+  if (changed.length) {
+    write(`warning: ${schemaPath} is stale against ${endpoint} (${changed.length} datasets changed since the pull) — re-run with --pull`)
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synthigy/sdk",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Zero-dependency client for Synthigy's /data endpoint",
   "author": "Robert Geršak",
   "license": "MIT",