@synthigy/sdk 0.2.0 → 0.2.2

package/README.md

@@ -60,7 +60,9 @@ Run it with `synthigy exec -- node hello.ts`.
   `watchSqlTemplate` for live analytics, `watch` for raw record events.
 
 - **`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
+  IAM / RBAC / row-level security enforced *server-side*; `whoami({ actingAs })`
+  shows who a call runs as — roles, superuser, whether this client may act as
+  users. Tokens never have to
   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

package/codegen/codegen.mjs

@@ -2,7 +2,6 @@
 // Unified codegen tool:
 //   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,7 +10,7 @@ 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'
 
 let tsVersion = null
@@ -29,10 +28,9 @@ synthigy-codegen — generate TypeScript types from XSQL operations
 Usage:
   codegen.mjs [flags] <a.xsql> [b.xsql ...] [outDir]   generate TS from one or more xsql files
   codegen.mjs check   [flags] <a.xsql> [b.xsql ...]    re-describe, diff IR, exit 1 on drift
-  codegen.mjs pull    [endpoint] [out]                  pull schema.json only
 
 Flags:
-  --pull               force schema refresh before generating
+  --pull               refresh schema.json beside the .xsql before generating
   --keys snake|camel   field key casing in generated types (default: snake)
   --no-writes          omit sync / stack / delete methods
   --schema <path>      explicit schema.json path (skips auto-pull)
@@ -47,7 +45,6 @@ Examples:
   node codegen.mjs movies.xsql src/generated/        first run auto-pulls schema
   node codegen.mjs --pull movies.xsql src/generated/ force schema refresh + generate
   node codegen.mjs check movies.xsql                 CI drift check
-  node codegen.mjs pull http://localhost:7887         pull schema only
 `.trim())
   process.exit(0)
 }
@@ -71,13 +68,6 @@ if (!VALID_KEYS.has(flags.keys)) {
 }
 
 const checkMode = pos[0] === 'check'
-const pullMode  = pos[0] === 'pull'
-
-if (pullMode) {
-  execFileSync(process.execPath, [path.join(here, 'pull.mjs'), ...pos.slice(1)],
-    { stdio: 'inherit', env: process.env })
-  process.exit(0)
-}
 
 // Positionals: last non-.xsql arg is outDir; everything before it (files or dirs)
 // is input. check mode has no outDir — every positional is input.
@@ -90,7 +80,6 @@ const xsqlArgs = hasExplicitOut ? rawPos.slice(0, -1) : rawPos
 if (!xsqlArgs.length) {
   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)')
   console.error('       --no-writes           omit sync/stack/delete methods')
@@ -99,6 +88,8 @@ if (!xsqlArgs.length) {
 }
 
 const isDir = p => fs.existsSync(p) && fs.statSync(p).isDirectory()
+const missing = xsqlArgs.filter(a => !fs.existsSync(path.resolve(a)))
+if (missing.length) { console.error(`no such .xsql file or directory: ${missing.join(', ')}`); process.exit(1) }
 const xsqlPaths = xsqlArgs.flatMap(a => {
   const p = path.resolve(a)
   if (isDir(p))
@@ -140,6 +131,8 @@ if (!flags.schemaOverride && (flags.pull || !fs.existsSync(schemaPath))) {
   execFileSync(process.execPath,
     [path.join(here, 'pull.mjs'), endpoint(), schemaPath],
     { stdio: 'inherit', env: process.env })
+} else {
+  await warnStaleSchema(ENDPOINT, schemaPath)
 }
 
 if (!fs.existsSync(schemaPath)) {

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/codegen/pull.mjs

@@ -21,8 +21,9 @@ import path from 'node:path'
 import { createClient } from '../src/index.js'
 
 const endpoint = process.argv[2] ?? process.env.SYNTHIGY_ENDPOINT
-if (!endpoint) {
-  console.error('usage: node pull.mjs <endpoint>   (or set SYNTHIGY_ENDPOINT)')
+const out = process.argv[3]
+if (!endpoint || !out) {
+  console.error('usage: node pull.mjs <endpoint> <schema.json>')
   process.exit(1)
 }
 
@@ -41,8 +42,7 @@ if (SYNTHIGY_CLIENT_ID && SYNTHIGY_CLIENT_SECRET) {
   config.token = SYNTHIGY_TOKEN ?? '' // '' = authless (bare server)
 }
 
-const here = path.dirname(new URL(import.meta.url).pathname)
-const outPath = process.argv[3] ? path.resolve(process.argv[3]) : path.join(here, 'schema.json')
+const outPath = path.resolve(out)
 
 const client = createClient(config)
 const schema = await client.schema()

package/package.json

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

package/src/browser-login.js

@@ -14,7 +14,8 @@
 import { pkce, decodeJwtPayload } from './login.js'
 
 const PENDING_PREFIX = 'synthigy.login:'
-const PENDING_TTL_MS = 5 * 60_000
+// must exceed the server's 8-minute login window, or slow logins fail LOGIN_STATE_UNKNOWN
+const PENDING_TTL_MS = 10 * 60_000
 const MESSAGE_SOURCE = 'synthigy-login'
 
 function randomToken(bytes) {

package/src/index.d.ts

@@ -275,6 +275,13 @@ export interface Schema {
  *   UNAUTHORIZED, CLIENT_NOT_FOUND, CLIENT_INACTIVE,
  *   PUBLIC_CLIENT_FORBIDDEN, NOT_TRUSTED, USER_NOT_FOUND, FORBIDDEN
  *
+ * Token mint refused (client credentials):
+ *   INVALID_CLIENT, INVALID_SCOPE, INVALID_AUDIENCE
+ *
+ * Permission denied (RBAC/RLS):
+ *   ENTITY_FORBIDDEN, RELATION_FORBIDDEN, ATTRIBUTE_FORBIDDEN,
+ *   ROW_FORBIDDEN, CREATE_FORBIDDEN, DELETE_FORBIDDEN, SLOT_OCCUPIED
+ *
  * Request shape:
  *   INVALID_BODY, NO_OPERATIONS, BAD_OP, MISSING_ENTITY,
  *   BAD_ARGS_SHAPE
@@ -302,6 +309,9 @@ export type SynthigyErrorCode =
   | 'UNAUTHORIZED' | 'CLIENT_NOT_FOUND' | 'CLIENT_INACTIVE'
   | 'PUBLIC_CLIENT_FORBIDDEN' | 'NOT_TRUSTED' | 'USER_NOT_FOUND'
   | 'FORBIDDEN' | 'NO_TOKEN'
+  | 'INVALID_CLIENT' | 'INVALID_SCOPE' | 'INVALID_AUDIENCE'
+  | 'ENTITY_FORBIDDEN' | 'RELATION_FORBIDDEN' | 'ATTRIBUTE_FORBIDDEN'
+  | 'ROW_FORBIDDEN' | 'CREATE_FORBIDDEN' | 'DELETE_FORBIDDEN' | 'SLOT_OCCUPIED'
   | 'NO_LOGIN_STORE' | 'LOGIN_REQUIRES_CONFIDENTIAL_CLIENT'
   | 'LOGIN_STATE_UNKNOWN' | 'LOGIN_NONCE_MISMATCH' | 'LOGIN_EXCHANGE_FAILED'
   | 'INVALID_BODY' | 'NO_OPERATIONS' | 'BAD_OP' | 'MISSING_ENTITY'
@@ -314,11 +324,50 @@ export type SynthigyErrorCode =
   | 'HTTP_ERROR' | 'OPERATION_ERROR' | 'INTERNAL_ERROR'
   | (string & {})
 
+/** `whoami()` — the identity a call runs as. `client` is null in-process (no OAuth client). */
+export interface WhoAmI {
+  xid: string | null
+  name: string | null
+  active: boolean
+  superuser: boolean
+  roles: string[]
+  groups: string[]
+  /** `trusted`: this client may act as users (confidential, active, flagged trusted). */
+  client: { id: string; trusted: boolean } | null
+}
+
+export type SynthigyErrorCategory =
+  | 'auth' | 'iam' | 'validation' | 'not_found'
+  | 'conflict' | 'rate_limit' | 'network' | 'internal'
+
+/** 1-based source position (XSQL_PARSE_ERROR, TEMPLATE_*). */
+export interface SourcePosition { line: number; col: number }
+
 export class SynthigyError extends Error {
   name: 'SynthigyError'
   code: SynthigyErrorCode
+  category: SynthigyErrorCategory
+  /** True for known network/rate_limit/internal codes, or when the server marked the error retryable. */
+  retryable: boolean
   details?: unknown
-  constructor(message: string, code: string, details?: unknown)
+  hint?: string
+  available?: string[]
+  path?: unknown
+  entity?: string
+  relation?: string
+  operator?: string
+  requestId?: string
+  status?: number
+  line?: number
+  col?: number
+  start?: SourcePosition
+  end?: SourcePosition
+  diagnostics?: unknown[]
+  constructor(message: string, code: string, details?: unknown, extras?: {
+    hint?: string; available?: string[]; path?: unknown; entity?: string; relation?: string
+    operator?: string; requestId?: string; status?: number; retryable?: boolean
+    line?: number; col?: number; start?: SourcePosition; end?: SourcePosition; diagnostics?: unknown[]
+  })
 }
 
 // ============================================================================
@@ -779,6 +828,9 @@ export class SynthigyClient {
    */
   deployedModel(opts?: ExecOpts): Promise<Record<string, unknown>>
 
+  /** Who a call runs as, after `actingAs` — roles, superuser, and whether this client may act as users. */
+  whoami(opts?: ExecOpts): Promise<WhoAmI>
+
   /**
    * Deploy a dataset version from a modeler export — pass the export file's
    * contents verbatim, the server decodes it. Requires `dataset:deploy`.
@@ -1200,6 +1252,7 @@ export const op: {
   query(xsql: string, params?: Record<string, unknown>, verb?: string): Operation
   deployedModel(): Operation
   runtimeModel(): Operation
+  whoami(): Operation
   deploy(exportContents: string): Operation
   destroy(datasetXid: string): Operation
 }
@@ -1281,6 +1334,7 @@ export const onboardComplete: SynthigyClient['onboardComplete']
 export const deploy: SynthigyClient['deploy']
 export const destroy: SynthigyClient['destroy']
 export const deployedModel: SynthigyClient['deployedModel']
+export const whoami: SynthigyClient['whoami']
 export const runtimeModel: SynthigyClient['runtimeModel']
 export const token: SynthigyClient['token']
 export function history(): SynthigyClient['history']

package/src/index.js

@@ -415,10 +415,7 @@ class TokenManager {
       body: params,
     })
 
-    if (!resp.ok) {
-      const text = await resp.text()
-      throw new Error(`Token request failed (${resp.status}): ${text}`)
-    }
+    if (!resp.ok) throw _tokenRefusal(resp.status, await resp.text())
 
     const data = await resp.json()
     this._tokens.set(key, {
@@ -434,6 +431,28 @@ class TokenManager {
   }
 }
 
+/** RFC 6749 §5.2 / RFC 8707 refusals with their own code; any other refusal is UNAUTHORIZED. */
+const REFUSAL_CODES = {
+  invalid_client: 'INVALID_CLIENT',
+  invalid_scope:  'INVALID_SCOPE',
+  invalid_target: 'INVALID_AUDIENCE',
+}
+
+function _tokenRefusal(status, text) {
+  let oauth = null
+  try { oauth = JSON.parse(text) } catch {}
+  if (typeof oauth?.error !== 'string' || oauth.error === '') {
+    return new SynthigyError(`Token request failed (${status}): ${text}`, 'UNAUTHORIZED', undefined, { status })
+  }
+  const code = Object.hasOwn(REFUSAL_CODES, oauth.error) ? REFUSAL_CODES[oauth.error] : 'UNAUTHORIZED'
+  const desc = typeof oauth.error_description === 'string' && oauth.error_description !== ''
+    ? ` — ${oauth.error_description}` : ''
+  return new SynthigyError(`Token request refused (${status}): ${oauth.error}${desc}`, code, oauth, {
+    status,
+    hint: code === 'INVALID_CLIENT' ? 'check the client id and secret, and that the client is active' : undefined,
+  })
+}
+
 // ============================================================================
 // Supervised stdio — SYNTHIGY_SUPERVISED=1. The SDK never mints locally
 // under this mode: the CLI/commander is the platform's stdio owner, so a
@@ -665,6 +684,10 @@ const ERROR_CATEGORIES = {
   LOGIN_NONCE_MISMATCH:       'auth',
   LOGIN_EXCHANGE_FAILED:      'auth',
   SILENT_TIMEOUT:             'auth',
+  USERINFO_SUB_MISMATCH:      'auth',
+  INVALID_CLIENT:             'auth',
+  INVALID_SCOPE:              'auth',
+  INVALID_AUDIENCE:           'auth',
   // OAuth error codes the IdP redirects back with (RFC 6749 4.1.2.1, OIDC 3.1.2.6)
   access_denied:              'auth',
   login_required:             'auth',
@@ -676,6 +699,12 @@ const ERROR_CATEGORIES = {
   ENTITY_FORBIDDEN:           'iam',
   ENTITY_NOT_READABLE:        'iam',
   RELATION_NOT_READABLE:      'iam',
+  RELATION_FORBIDDEN:         'iam',
+  ATTRIBUTE_FORBIDDEN:        'iam',
+  ROW_FORBIDDEN:              'iam',
+  CREATE_FORBIDDEN:           'iam',
+  DELETE_FORBIDDEN:           'iam',
+  SLOT_OCCUPIED:              'iam',
   // validation
   INVALID_BODY:               'validation',
   NO_OPERATIONS:              'validation',
@@ -732,11 +761,14 @@ const ERROR_CATEGORIES = {
   INTERNAL_ERROR:             'internal',
   OPERATION_ERROR:            'internal',
   HTTP_ERROR:                 'internal',
+  OPERATION_FAILED:           'internal',
+  USERINFO_FAILED:            'internal',
 }
 
 /**
  * Codes whose category is automatically retryable. Any other code is
- * one-shot: the caller must fix something before retrying.
+ * one-shot: the caller must fix something before retrying. A code missing
+ * from ERROR_CATEGORIES is retryable only when the server marks it so.
  */
 const RETRYABLE_CATEGORIES = new Set(['network', 'rate_limit', 'internal'])
 
@@ -777,7 +809,9 @@ export class SynthigyError extends Error {
     this.name      = 'SynthigyError'
     this.code      = code
     this.category  = ERROR_CATEGORIES[code] ?? 'internal'
-    this.retryable = RETRYABLE_CATEGORIES.has(this.category)
+    this.retryable = typeof extras?.retryable === 'boolean'
+      ? extras.retryable
+      : Object.hasOwn(ERROR_CATEGORIES, code) && RETRYABLE_CATEGORIES.has(this.category)
     if (details !== undefined) this.details = details
     if (extras) {
       if (extras.hint        !== undefined) this.hint        = extras.hint
@@ -833,6 +867,7 @@ function _errorFromServer(err, status, requestId) {
     start:       err.start,
     end:         err.end,
     diagnostics: err.diagnostics,
+    retryable:   err.retryable,
     requestId,
     status,
   })
@@ -1968,6 +2003,19 @@ class SynthigyClient {
     return result.data
   }
 
+  /**
+   * Who a call runs as, after `actingAs`: xid, name, active, superuser, roles,
+   * groups, and `client` ({ id, trusted }) — trusted means it may act as users.
+   *
+   * @param {Object} [opts] - Options ({ actingAs })
+   * @returns {Promise<Object>}
+   */
+  async whoami(opts) {
+    const [result] = await this.exec([{ op: 'whoami' }], opts)
+    if (!result.ok) throw _errorFromServer(result.error, undefined, result._requestId)
+    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`.
@@ -2526,6 +2574,7 @@ export const op = {
   query:       (xsql, params, verb = 'search') => ({ op: 'xsql', xsql: xsqlDocument(xsql, verb), ...(params !== undefined && { params }) }),
   deployedModel: () => ({ op: 'deployed-model' }),
   runtimeModel: () => ({ op: 'runtime-model' }),
+  whoami:       ()                       => ({ op: 'whoami' }),
   deploy:       (exportContents)         => ({ op: 'deploy', data: exportContents }),
   destroy:      (datasetXid)             => ({ op: 'delete', entity: 'dataset', data: { xid: datasetXid } }),
 }
@@ -2657,6 +2706,7 @@ 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 whoami        = (...a) => _dflt().whoami(...a)
 export const runtimeModel  = (...a) => _dflt().runtimeModel(...a)
 export const token         = (...a) => _dflt().token(...a)
 export const history       = () => _dflt().history

package/src/login.js

@@ -13,7 +13,8 @@
 
 const PKCE_VERIFIER_BYTES = 32
 const STATE_BYTES = 24
-const DEFAULT_TTL_MS = 5 * 60_000
+// must exceed the server's 8-minute login window, or slow logins fail LOGIN_STATE_UNKNOWN
+const LOGIN_TTL_MS = 10 * 60_000
 
 function base64urlEncode(bytes) {
   let binary = ''
@@ -69,7 +70,7 @@ export function decodeJwtPayload(jwt) {
  * holds their sessions (Redis, Postgres, a signed cookie).
  */
 export class MemoryLoginStore {
-  constructor({ ttlMs = DEFAULT_TTL_MS } = {}) {
+  constructor({ ttlMs = LOGIN_TTL_MS } = {}) {
     this._ttlMs = ttlMs
     this._pending = new Map()
   }
@@ -127,6 +128,12 @@ export function createLoginApi(client, { SynthigyError }) {
     }
   }
 
+  // the store's own expiry is not trusted: one that never expires would accept a login of any age
+  const takePending = async (state) => {
+    const pending = state ? await client._loginStore.take(state) : null
+    return pending && pending.createdAt > Date.now() - LOGIN_TTL_MS ? pending : null
+  }
+
   return {
     /**
      * Begin a login: returns the URL to redirect the browser to, and stashes
@@ -167,7 +174,7 @@ export function createLoginApi(client, { SynthigyError }) {
      */
     async complete({ code, state, redirectUri } = {}) {
       requireConfidential()
-      const pending = state ? await client._loginStore.take(state) : null
+      const pending = await takePending(state)
       if (!pending) {
         throw new SynthigyError(
           'unknown or expired login state: the store never saw it, it was ' +
@@ -230,7 +237,7 @@ export function createLoginApi(client, { SynthigyError }) {
      * here rather than a throw.
      */
     async cancel(state) {
-      const pending = state ? await client._loginStore.take(state) : null
+      const pending = await takePending(state)
       return pending ? { returnTo: pending.returnTo } : null
     },
   }