@synthigy/sdk 0.1.0 → 0.1.2

package/README.md

@@ -66,7 +66,7 @@ for await (const ev of w.events) {
   IAM / RBAC / row-level security enforced *server-side*. Tokens never have to
   reach the browser. → [AUTH.md](./docs/AUTH.md)
 
-- **Typed from your model.** `synthigy-gen` compiles your ERD + `.xsql` files
+- **Typed from your model.** `synthigy-gen` (needs `typescript` in your project) 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)
 
@@ -79,8 +79,7 @@ for await (const ev of w.events) {
 | [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 |
-| [examples/datastar-movies/](./examples/datastar-movies/) | End-to-end BFF exercising every primitive |
-| [examples/movies-live.mjs](./examples/movies-live.mjs) | Minimal live-watch demo |
+| [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 |
 
 ## Tests

package/codegen/codegen.mjs

@@ -10,8 +10,21 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { createHash } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
-import ts from 'typescript'
+import { createRequire } from 'node:module'
 import { TS, tsScalar, pascal, camel } 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
+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)
+}
 
 const here = path.dirname(new URL(import.meta.url).pathname)
 
@@ -44,6 +57,7 @@ Environment:
   SYNTHIGY_ENDPOINT        server URL (default: http://localhost:7887)
   SYNTHIGY_CLIENT_ID       OAuth client ID
   SYNTHIGY_CLIENT_SECRET   OAuth client secret
+  SYNTHIGY_AUDIENCE        client_credentials audience, when the server requires one
 
 Examples:
   node codegen.mjs movies.xsql src/generated/        first run auto-pulls schema
@@ -124,7 +138,7 @@ const toKey = flags.keys === 'camel' ? camel : s => s
 
 // ── describe ─────────────────────────────────────────────────────────────────
 const ENDPOINT = process.env.SYNTHIGY_ENDPOINT ?? 'http://localhost:7887'
-const { SYNTHIGY_CLIENT_ID, SYNTHIGY_CLIENT_SECRET } = process.env
+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))) {
@@ -144,7 +158,11 @@ async function token() {
     method: 'POST',
     headers: { 'content-type': 'application/x-www-form-urlencoded' },
     body: new URLSearchParams({ grant_type: 'client_credentials',
-      client_id: SYNTHIGY_CLIENT_ID, client_secret: SYNTHIGY_CLIENT_SECRET }),
+      client_id: SYNTHIGY_CLIENT_ID, client_secret: SYNTHIGY_CLIENT_SECRET,
+      // describe is a platform-API call like any other, so it mints for the
+      // platform audience. Hand-rolled here rather than going through the
+      // client, so the default has to be named explicitly.
+      audience: SYNTHIGY_AUDIENCE || PLATFORM_AUDIENCE }),
   })
   if (!r.ok) throw new Error(`token ${r.status}: ${await r.text()}`)
   return (await r.json()).access_token
@@ -194,7 +212,15 @@ if (cached && cached.sourceHash === sourceHash) {
     if (!resp.ok) throw new Error(`describe ${resp.status}: ${await resp.text()}`)
     const body = await resp.json()
     const r0   = (body.results ?? body.result ?? [body.data ?? body])[0] ?? body
+    // A describe that fails answers 200 with {ok:false, error} in the result.
+    // Reading .operations off that yields "not iterable" and throws the
+    // server's diagnostic away — which is the only thing that says WHICH
+    // attribute the templates got wrong.
+    const err = r0?.error ?? (r0?.ok === false ? { message: 'describe failed' } : null)
+    if (err) throw new Error(err.message ?? JSON.stringify(err))
     ir = r0.result ?? r0.data ?? r0
+    if (!Array.isArray(ir?.operations))
+      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`
@@ -239,7 +265,13 @@ fs.writeFileSync(irPath, JSON.stringify(ir, null, 2) + '\n')
 // Identity (namespace / name), @watch, and sql-template @returns results all come
 // from the IR now — the canonical XSQL parser owns them. No XSQL re-parsing here.
 const schema  = JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
-const sdkSrc  = path.relative(outDir, path.join(here, '..', 'src')) + '/index.js'
+// Installed from npm -> import the package by name; a relative path out of
+// node_modules is correct only for one install layout. Inside this repo the
+// relative path is still what works, since there is no package to resolve.
+const sdkRoot = path.join(here, '..')
+const sdkSrc  = sdkRoot.includes(`${path.sep}node_modules${path.sep}`)
+  ? '@synthigy/sdk'
+  : path.relative(outDir, path.join(sdkRoot, 'src')) + '/index.js'
 const ent     = (n) => schema.entities[n] ?? {}
 const visited = new Set()
 
@@ -329,7 +361,14 @@ for (const n of allEntities) nsOf(entityPascal(n))
 // never emitted from XSQL. Skip LOUDLY, never silently.
 const MUTATE_VERBS = new Set(['sync', 'stack', 'delete'])
 for (const op of ir.operations) {
-  if (op.batch) continue
+  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`)
+    continue
+  }
   if (MUTATE_VERBS.has(op.op)) {
     console.warn(`skipped @${op.op} ${op.name} — mutations are generated from the schema; use ${entityPascal(op.entity ?? '<Entity>')}.${op.op}(data)`)
     continue
@@ -478,20 +517,42 @@ fs.writeFileSync(path.join(outDir, 'ops.ts'),    OPS_HDR_COMMENT + formatTs(OPS_
 // type-check — never ship broken/stale output silently (the old emit-and-swallow
 // shipped a stale ops.js once). No .js emitted: consumers import the .ts source
 // (Node 23+ type-stripping / a bundler); the type-only `./schema.js` import erases
-// at runtime. `--ignoreConfig` so a consumer tsconfig can't trip TS5112.
-const tscBin = path.join(here, '..', 'node_modules', '.bin', 'tsc')
-try {
-  execFileSync(tscBin, [
-    '--ignoreConfig',
-    '--module', 'nodenext', '--moduleResolution', 'nodenext',
-    '--target', 'es2022', '--strict', '--skipLibCheck', '--noEmit',
-    path.join(outDir, 'ops.ts'),
-    path.join(outDir, 'schema.ts'),
-  ], { stdio: 'pipe' })
-} catch (e) {
-  process.stderr.write('codegen: generated TS failed to type-check (not shipped):\n')
-  process.stderr.write((e.stdout ?? e.stderr ?? '').toString())
-  process.exit(1)
+// at runtime.
+// Locate tsc through the SAME resolution that found the `typescript` module
+// above, so a hoisted install — the normal consumer layout — is found. A path
+// built from `here` only exists when typescript is nested under this package.
+const tscBin = (() => {
+  try {
+    const lib = createRequire(import.meta.url).resolve('typescript')
+    const bin = path.join(path.dirname(lib), '..', 'bin', 'tsc')
+    if (fs.existsSync(bin)) return bin
+  } catch {}
+  for (const c of [path.join(here, '..', 'node_modules', '.bin', 'tsc'),
+                   path.join(process.cwd(), 'node_modules', '.bin', 'tsc')]) {
+    if (fs.existsSync(c)) return c
+  }
+  return null
+})()
+
+// `--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
+if (tscBin) {
+  try {
+    execFileSync(tscBin, [
+      ...(tscMajor >= 6 ? ['--ignoreConfig'] : []),
+      '--module', 'nodenext', '--moduleResolution', 'nodenext',
+      '--target', 'es2022', '--strict', '--skipLibCheck', '--noEmit',
+      path.join(outDir, 'ops.ts'),
+      path.join(outDir, 'schema.ts'),
+    ], { stdio: 'pipe' })
+  } catch (e) {
+    process.stderr.write('codegen: generated TS failed to type-check (not shipped):\n')
+    process.stderr.write((e.stdout ?? e.stderr ?? '').toString())
+    process.exit(1)
+  }
+} else {
+  process.stderr.write('codegen: tsc not found — skipping the type-check gate.\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

package/codegen/pull.mjs

@@ -26,11 +26,17 @@ if (!endpoint) {
   process.exit(1)
 }
 
-const { SYNTHIGY_TOKEN, SYNTHIGY_CLIENT_ID, SYNTHIGY_CLIENT_SECRET } = process.env
+const { SYNTHIGY_TOKEN, SYNTHIGY_CLIENT_ID, SYNTHIGY_CLIENT_SECRET,
+        SYNTHIGY_AUDIENCE } = process.env
 const config = { endpoint }
 if (SYNTHIGY_CLIENT_ID && SYNTHIGY_CLIENT_SECRET) {
   config.clientId = SYNTHIGY_CLIENT_ID
   config.clientSecret = SYNTHIGY_CLIENT_SECRET
+  // A server can require an explicit client_credentials audience for /data and
+  // /schema. Without it the mint still succeeds and the token is then refused,
+  // so the symptom is a 401 on schema rather than anything about auth config.
+  // A static SYNTHIGY_TOKEN already has its audience baked in.
+  if (SYNTHIGY_AUDIENCE) config.audience = SYNTHIGY_AUDIENCE
 } else {
   config.token = SYNTHIGY_TOKEN ?? '' // '' = authless (bare server)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synthigy/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Zero-dependency client for Synthigy's /data endpoint",
   "author": "Robert Geršak",
   "license": "MIT",
@@ -50,6 +50,14 @@
     "realtime",
     "xsql"
   ],
+  "peerDependencies": {
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "typescript": "^6.0.3"
   },

package/src/index.d.ts

@@ -1,3 +1,6 @@
+/** The platform API this SDK is a client of; the default audience for every mint. */
+export const PLATFORM_AUDIENCE: "https://synthigy.com"
+
 // ============================================================================
 // Selection
 // ============================================================================
@@ -79,6 +82,13 @@ export interface TreeExecOpts extends ExecOpts {
   childrenKey?: string
 }
 
+/** What `deploy()` acks with — `dataset` is the xid `destroy()` takes. */
+export interface DeployAck {
+  deployed: boolean
+  version: string
+  dataset: string
+}
+
 export type OperationResult<T = unknown> =
   | { ok: true; data: T }
   | { ok: false; error: { message: string; code: string } }
@@ -608,6 +618,19 @@ export class SynthigyClient {
    */
   deployedModel(opts?: ExecOpts): Promise<Record<string, unknown>>
 
+  /**
+   * Deploy a dataset version from a modeler export — pass the export file's
+   * contents verbatim, the server decodes it. Requires `dataset:deploy`.
+   * The ack carries the dataset xid `destroy()` takes.
+   */
+  deploy(exportContents: string, opts?: ExecOpts): Promise<DeployAck>
+
+  /**
+   * Destroy a dataset — every version, table and row. Requires
+   * `dataset:delete`. Idempotent.
+   */
+  destroy(datasetXid: string, opts?: ExecOpts): Promise<boolean>
+
   /**
    * Fetch the runtime (enhanced) ERD model via `op: "runtime-model"` —
    * the model as the running system actually emits it, with audit
@@ -1014,6 +1037,8 @@ export const op: {
   sqlTemplate(template: string, params?: Record<string, unknown> | unknown[], opts?: { cached?: boolean }): Operation
   deployedModel(): Operation
   runtimeModel(): Operation
+  deploy(exportContents: string): Operation
+  destroy(datasetXid: string): Operation
 }
 
 // ============================================================================
@@ -1087,6 +1112,8 @@ export { _delete as delete }
 
 export const schema: SynthigyClient['schema']
 export const lint: SynthigyClient['lint']
+export const deploy: SynthigyClient['deploy']
+export const destroy: SynthigyClient['destroy']
 export const deployedModel: SynthigyClient['deployedModel']
 export const runtimeModel: SynthigyClient['runtimeModel']
 export const token: SynthigyClient['token']

package/src/index.js

@@ -733,6 +733,15 @@ const RETRYABLE_CATEGORIES = new Set(['network', 'rate_limit', 'internal'])
  *   - .requestId— request ID for cross-correlation with server logs
  *   - .status   — HTTP status code (for transport-level errors)
  */
+/**
+ * The platform API this SDK is a client of. `/data`, `/schema`, `/history`,
+ * `/logs` and subscriptions all require a token bound to it. It identifies the
+ * API, never a deployment, so it is the same string on localhost and in
+ * production — which is exactly why it is a constant here rather than
+ * something every caller configures.
+ */
+export const PLATFORM_AUDIENCE = 'https://synthigy.com'
+
 export class SynthigyError extends Error {
   constructor(message, code, details, extras) {
     super(message)
@@ -870,12 +879,16 @@ class SynthigyClient {
     // [sub, client_id] isn't torn down between watches. Replaces the
     // earlier "dummy keepalive watch" workaround.
     this._keepAlive = config.keepAlive === true
-    // The platform's audience model is opt-in: a client_credentials mint
-    // naming no audience resolves to the identity-only OIDC audience, which
-    // /data rejects. Bound once here, applied to every mint this client makes.
+    // A client_credentials mint naming no audience resolves to the
+    // identity-only OIDC audience, which /data rejects. This SDK is the client
+    // for the platform API, so PLATFORM_AUDIENCE is what it asks for — there
+    // is nothing for a caller to configure, and nowhere to look the value up
+    // if there were: the server does not advertise it in discovery. Minting a
+    // token for some OTHER API is a per-call argument on token(), not a
+    // property of the client. The env var stays only as an escape hatch.
     this._defaultAudience = config.audience
       ?? (typeof process !== 'undefined' ? process.env?.SYNTHIGY_AUDIENCE : undefined)
-      ?? undefined
+      ?? PLATFORM_AUDIENCE
 
     if (config.token !== undefined && config.token !== null) {
       // Static token mode — empty string allowed for unauth / dev servers.
@@ -1863,6 +1876,34 @@ class SynthigyClient {
     return result.data
   }
 
+  /**
+   * Deploy a dataset version from a modeler export. Pass the export file's
+   * contents verbatim — the server decodes it. Requires `dataset:deploy`.
+   *
+   * @param {string} exportContents - Contents of a `<Dataset>@<version>.json` export
+   * @param {Object} [opts] - Options ({ actingAs })
+   * @returns {Promise<{deployed: boolean, version: string, dataset: string}>}
+   */
+  async deploy(exportContents, opts) {
+    const [result] = await this.exec([{ op: 'deploy', data: exportContents }], opts)
+    if (!result.ok) throw _errorFromServer(result.error, undefined, result._requestId)
+    return result.data
+  }
+
+  /**
+   * Destroy a dataset: every version, every table, every row. Requires
+   * `dataset:delete`. Idempotent — a dataset that is already gone is not an error.
+   *
+   * @param {string} datasetXid - The dataset xid (`deploy()` returns it)
+   * @param {Object} [opts] - Options ({ actingAs })
+   * @returns {Promise<boolean>}
+   */
+  async destroy(datasetXid, opts) {
+    const [result] = await this.exec([{ op: 'delete', entity: 'dataset', data: { xid: datasetXid } }], opts)
+    if (!result.ok) throw _errorFromServer(result.error, undefined, result._requestId)
+    return result.data
+  }
+
   /**
    * Fetch the runtime ERD model — the deployed model augmented with:
    *   - `xid` / `euuid` identity attrs on every entity
@@ -2387,6 +2428,8 @@ export const op = {
   sqlTemplate: (template, params)        => ({ op: 'sql-template', template, params: params || [] }),
   deployedModel: () => ({ op: 'deployed-model' }),
   runtimeModel: () => ({ op: 'runtime-model' }),
+  deploy:       (exportContents)         => ({ op: 'deploy', data: exportContents }),
+  destroy:      (datasetXid)             => ({ op: 'delete', entity: 'dataset', data: { xid: datasetXid } }),
 }
 
 // ============================================================================
@@ -2512,6 +2555,8 @@ export const schema        = (...a) => _dflt().schema(...a)
 export const lint          = (...a) => _dflt().lint(...a)
 export const onboard       = (...a) => _dflt().onboard(...a)
 export const onboardComplete = (...a) => _dflt().onboardComplete(...a)
+export const deploy        = (...a) => _dflt().deploy(...a)
+export const destroy       = (...a) => _dflt().destroy(...a)
 export const deployedModel = (...a) => _dflt().deployedModel(...a)
 export const runtimeModel  = (...a) => _dflt().runtimeModel(...a)
 export const token         = (...a) => _dflt().token(...a)