@synthigy/sdk 0.2.0 → 0.2.1

package/codegen/codegen.mjs

@@ -11,7 +11,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
@@ -140,6 +140,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synthigy/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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'

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,
   })

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
     },
   }