@xylex-group/athena 2.8.2 → 2.9.0

package/dist/cli/index.cjs

@@ -688,6 +688,77 @@ function resolveProviderSchemas(providerConfig) {
   return [...DEFAULT_POSTGRES_SCHEMAS];
 }
 
+// src/generator/table-selection.ts
+function normalizeTableSelector(value) {
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function normalizeTableSelection(value) {
+  if (typeof value === "string") {
+    return Array.from(
+      new Set(
+        value.split(",").map(normalizeTableSelector).filter((entry) => Boolean(entry))
+      )
+    );
+  }
+  if (Array.isArray(value)) {
+    return Array.from(
+      new Set(
+        value.map((entry) => typeof entry === "string" ? normalizeTableSelector(entry) : void 0).filter((entry) => Boolean(entry))
+      )
+    );
+  }
+  return [];
+}
+function matchesTableSelector(schemaName, tableName, selector) {
+  const separatorIndex = selector.indexOf(".");
+  if (separatorIndex < 0) {
+    return tableName === selector;
+  }
+  const selectorSchema = selector.slice(0, separatorIndex).trim();
+  const selectorTable = selector.slice(separatorIndex + 1).trim();
+  return selectorSchema === schemaName && selectorTable === tableName;
+}
+function shouldKeepTable(schemaName, tableName, filter) {
+  const included = filter.includeTables.length === 0 || filter.includeTables.some((selector) => matchesTableSelector(schemaName, tableName, selector));
+  if (!included) {
+    return false;
+  }
+  return !filter.excludeTables.some((selector) => matchesTableSelector(schemaName, tableName, selector));
+}
+function hasTableFilters(filter) {
+  return filter.includeTables.length > 0 || filter.excludeTables.length > 0;
+}
+function filterIntrospectionSnapshot(snapshot, filter) {
+  if (!hasTableFilters(filter)) {
+    return snapshot;
+  }
+  const schemas = {};
+  for (const [schemaName, schema] of Object.entries(snapshot.schemas)) {
+    const tables = Object.fromEntries(
+      Object.entries(schema.tables).filter(([tableName]) => shouldKeepTable(schemaName, tableName, filter))
+    );
+    if (Object.keys(tables).length === 0) {
+      continue;
+    }
+    schemas[schemaName] = {
+      ...schema,
+      tables
+    };
+  }
+  if (Object.keys(schemas).length === 0) {
+    const includeLabel = filter.includeTables.length > 0 ? ` includeTables=${filter.includeTables.join(", ")}` : "";
+    const excludeLabel = filter.excludeTables.length > 0 ? ` excludeTables=${filter.excludeTables.join(", ")}` : "";
+    throw new Error(
+      `Generator table filters matched no tables after schema selection.${includeLabel}${excludeLabel}`
+    );
+  }
+  return {
+    ...snapshot,
+    schemas
+  };
+}
+
 // src/generator/config.ts
 var POSTGRES_PROTOCOLS = /* @__PURE__ */ new Set(["postgres:", "postgresql:"]);
 var DEFAULT_CONFIG_CANDIDATES = [
@@ -698,13 +769,20 @@ var DEFAULT_CONFIG_CANDIDATES = [
   ".athena.config.ts",
   ".athena.config.js"
 ];
-var DEFAULT_TARGETS = {
+var LEGACY_DEFAULT_TARGETS = {
   model: "athena/models/{schema_kebab}/{model_kebab}.ts",
   schema: "athena/schemas/{schema_kebab}.ts",
   database: "athena/relations.ts",
   registry: "athena/config.ts"
 };
-var DEFAULT_OUTPUT_FORMAT = "define-model";
+var ATHENA_DIRECT_TARGETS = {
+  model: "athena/models/{schema_kebab}/{model_kebab}.ts",
+  schema: "athena/schemas/{schema_kebab}.ts",
+  database: "athena/relations.ts",
+  registry: "athena/registry.generated.ts"
+};
+var DEFAULT_OUTPUT_FORMAT = "table-builder";
+var DEFAULT_OUTPUT_PRESET = "athena-direct";
 var DEFAULT_NAMING = {
   modelType: "pascal",
   modelConst: "camel",
@@ -723,6 +801,10 @@ var DEFAULT_EXPERIMENTAL_FLAGS = {
 var DEFAULT_INTERNAL_CONFIG = {
   schemaVersion: 1
 };
+var DEFAULT_FILTER_CONFIG = {
+  includeTables: [],
+  excludeTables: []
+};
 var PROJECT_ENV_FILENAMES = [".env", ".env.local"];
 var DIRECT_CONNECTION_STRING_ENV_KEYS = [
   "ATHENA_GENERATOR_PG_URL",
@@ -741,10 +823,13 @@ var GATEWAY_API_KEY_ENV_KEYS = [
 ];
 var GENERATOR_SCHEMA_ENV_KEYS = ["ATHENA_GENERATOR_SCHEMAS"];
 var OUTPUT_FORMAT_ENV_KEYS = ["ATHENA_GENERATOR_OUTPUT_FORMAT"];
+var OUTPUT_PRESET_ENV_KEYS = ["ATHENA_GENERATOR_OUTPUT_PRESET"];
 var MODEL_TARGET_ENV_KEYS = ["ATHENA_GENERATOR_MODEL_TARGET"];
 var SCHEMA_TARGET_ENV_KEYS = ["ATHENA_GENERATOR_SCHEMA_TARGET"];
 var DATABASE_TARGET_ENV_KEYS = ["ATHENA_GENERATOR_DATABASE_TARGET"];
 var REGISTRY_TARGET_ENV_KEYS = ["ATHENA_GENERATOR_REGISTRY_TARGET"];
+var TABLES_ENV_KEYS = ["ATHENA_GENERATOR_TABLES"];
+var EXCLUDE_TABLES_ENV_KEYS = ["ATHENA_GENERATOR_EXCLUDE_TABLES"];
 var PLACEHOLDER_MAP_ENV_KEYS = ["ATHENA_GENERATOR_PLACEHOLDER_MAP"];
 var MODEL_TYPE_ENV_KEYS = ["ATHENA_GENERATOR_MODEL_TYPE", "ATHENA_GENERATOR_MODEL_STYLE"];
 var MODEL_CONST_ENV_KEYS = ["ATHENA_GENERATOR_MODEL_CONST"];
@@ -759,7 +844,12 @@ var SCYLLA_PROVIDER_CONTRACTS_ENV_KEYS = ["ATHENA_GENERATOR_SCYLLA_PROVIDER_CONT
 var ENV_ONLY_CONFIG_PATH = "[environment defaults]";
 var NAMING_STYLE_VALUES = ["preserve", "camel", "pascal", "snake", "kebab"];
 var OUTPUT_FORMAT_VALUES = ["define-model", "table-builder"];
+var OUTPUT_PRESET_VALUES = ["legacy", "athena-direct"];
 var BACKEND_TYPE_VALUES = ["athena", "postgrest", "postgresql", "scylladb"];
+var OUTPUT_PRESET_TARGETS = {
+  legacy: LEGACY_DEFAULT_TARGETS,
+  "athena-direct": ATHENA_DIRECT_TARGETS
+};
 function normalizeRawEnvValue(rawValue) {
   if (rawValue.startsWith('"') && rawValue.endsWith('"') && rawValue.length >= 2) {
     const inner = rawValue.slice(1, -1);
@@ -966,11 +1056,19 @@ function normalizeExperimentalFlags(input) {
     )
   };
 }
+function normalizeFilterConfig(input) {
+  return {
+    includeTables: normalizeTableSelection(input?.includeTables),
+    excludeTables: normalizeTableSelection(input?.excludeTables)
+  };
+}
 function normalizeOutputConfig(output) {
+  const preset = output?.preset ?? DEFAULT_OUTPUT_PRESET;
   return {
     format: output?.format ?? DEFAULT_OUTPUT_FORMAT,
+    preset,
     targets: {
-      ...DEFAULT_TARGETS,
+      ...OUTPUT_PRESET_TARGETS[preset],
       ...output?.targets ?? {}
     },
     placeholderMap: {
@@ -1050,6 +1148,10 @@ function normalizeGeneratorConfig(input) {
       ...DEFAULT_NAMING,
       ...input.naming ?? {}
     },
+    filter: {
+      ...DEFAULT_FILTER_CONFIG,
+      ...normalizeFilterConfig(input.filter)
+    },
     features: normalizeFeatureFlags(input.features),
     experimental: normalizeExperimentalFlags(input.experimental),
     internal: {
@@ -1110,16 +1212,18 @@ function importConfigModule(moduleSpecifier) {
 }
 function buildEnvironmentOutputConfig() {
   const format = resolveOptionalOneOf(OUTPUT_FORMAT_ENV_KEYS, OUTPUT_FORMAT_VALUES);
+  const preset = resolveOptionalOneOf(OUTPUT_PRESET_ENV_KEYS, OUTPUT_PRESET_VALUES);
   const modelTarget = resolveFallbackValue(MODEL_TARGET_ENV_KEYS);
   const schemaTarget = resolveFallbackValue(SCHEMA_TARGET_ENV_KEYS);
   const databaseTarget = resolveFallbackValue(DATABASE_TARGET_ENV_KEYS);
   const registryTarget = resolveFallbackValue(REGISTRY_TARGET_ENV_KEYS);
   const placeholderMap = resolveOptionalJson(PLACEHOLDER_MAP_ENV_KEYS);
-  if (format === void 0 && modelTarget === void 0 && schemaTarget === void 0 && databaseTarget === void 0 && registryTarget === void 0 && placeholderMap === void 0) {
+  if (format === void 0 && preset === void 0 && modelTarget === void 0 && schemaTarget === void 0 && databaseTarget === void 0 && registryTarget === void 0 && placeholderMap === void 0) {
     return void 0;
   }
   return {
     format,
+    preset,
     targets: {
       ...modelTarget ? { model: modelTarget } : {},
       ...schemaTarget ? { schema: schemaTarget } : {},
@@ -1129,6 +1233,17 @@ function buildEnvironmentOutputConfig() {
     placeholderMap
   };
 }
+function buildEnvironmentFilterConfig() {
+  const includeTables = resolveFallbackValue(TABLES_ENV_KEYS);
+  const excludeTables = resolveFallbackValue(EXCLUDE_TABLES_ENV_KEYS);
+  if (includeTables === void 0 && excludeTables === void 0) {
+    return void 0;
+  }
+  return {
+    ...includeTables !== void 0 ? { includeTables } : {},
+    ...excludeTables !== void 0 ? { excludeTables } : {}
+  };
+}
 function buildEnvironmentNamingConfig() {
   const modelType = resolveOptionalOneOf(MODEL_TYPE_ENV_KEYS, NAMING_STYLE_VALUES);
   const modelConst = resolveOptionalOneOf(MODEL_CONST_ENV_KEYS, NAMING_STYLE_VALUES);
@@ -1204,6 +1319,7 @@ function createEnvironmentGeneratorConfig() {
     provider,
     output: buildEnvironmentOutputConfig(),
     naming: buildEnvironmentNamingConfig(),
+    filter: buildEnvironmentFilterConfig(),
     features: buildEnvironmentFeatureFlags(),
     experimental: buildEnvironmentExperimentalFlags()
   };
@@ -1365,7 +1481,7 @@ ${schemaEntries}
     content
   };
 }
-function renderRegistryArtifact(registryPath, databasePath, databaseConstName, registryConstName, databaseName, generatedAt, outputFormat, schemaVersion) {
+function renderRegistryArtifact(registryPath, databasePath, databaseConstName, registryConstName, databaseName, generatedAt, outputPreset, outputFormat, schemaVersion) {
   const databaseImportPath = toModuleImportPath(registryPath, databasePath);
   const content = `import { defineRegistry } from '@xylex-group/athena'
 import { ${databaseConstName} } from '${databaseImportPath}'
@@ -1374,6 +1490,7 @@ export const __athena_schema_meta = {
   schemaVersion: ${schemaVersion},
   generatedAt: ${escapeStringLiteral(generatedAt)},
   database: ${escapeStringLiteral(databaseName)},
+  outputPreset: ${escapeStringLiteral(outputPreset)},
   outputFormat: ${escapeStringLiteral(outputFormat)},
 } as const
 
@@ -1543,6 +1660,7 @@ function composeGeneratorArtifacts(input) {
         toSafeIdentifier("registry", config.naming.registryConst, "registry"),
         databaseName,
         snapshot.generatedAt,
+        config.output.preset,
         config.output.format,
         config.internal.schemaVersion
       )
@@ -1648,7 +1766,7 @@ export const ${descriptor.tableConstName} = table(${escapeStringLiteral(descript
   .columns({
 ${columnLines}
   })
-  .primaryKey(${descriptor.table.primaryKey.map((value) => escapeStringLiteral(value)).join(", ")})
+  ${descriptor.table.primaryKey.length > 0 ? `.primaryKey(${descriptor.table.primaryKey.map((value) => escapeStringLiteral(value)).join(", ")})` : ".withoutPrimaryKey()"}
 ${relationsAssignment ? `${relationsAssignment}` : ""}
 export type ${descriptor.rowTypeName} = RowOf<typeof ${descriptor.tableConstName}>
 export type ${descriptor.insertTypeName} = InsertOf<typeof ${descriptor.tableConstName}>
@@ -1745,11 +1863,12 @@ ${nullableLines}
 }
 function generateArtifactsFromSnapshot(snapshot, config) {
   const normalizedConfig = "internal" in config ? config : normalizeGeneratorConfig(config);
+  const filteredSnapshot = filterIntrospectionSnapshot(snapshot, normalizedConfig.filter);
   if (normalizedConfig.output.format === "table-builder") {
-    return generateTableBuilderArtifactsFromSnapshot(snapshot, normalizedConfig);
+    return generateTableBuilderArtifactsFromSnapshot(filteredSnapshot, normalizedConfig);
   }
   return composeGeneratorArtifacts({
-    snapshot,
+    snapshot: filteredSnapshot,
     config: normalizedConfig,
     createModelDescriptor({ providerName, databaseName, schemaName, tableName, table }) {
       const modelConstName = toSafeIdentifier(
@@ -1779,7 +1898,7 @@ function generateArtifactsFromSnapshot(snapshot, config) {
         table
       };
     },
-    renderModelArtifact: (descriptor) => renderModelArtifact2(snapshot.database, descriptor, normalizedConfig)
+    renderModelArtifact: (descriptor) => renderModelArtifact2(filteredSnapshot.database, descriptor, normalizedConfig)
   });
 }
 
@@ -1885,7 +2004,7 @@ var getSessionCookie = (request, config) => {
 
 // package.json
 var package_default = {
-  version: "2.8.2"
+  version: "2.9.0"
 };
 
 // src/sdk-version.ts
@@ -1898,6 +2017,7 @@ function buildSdkHeaderValue(sdkName) {
 var DEFAULT_CLIENT = "railway_direct";
 var SDK_NAME = "xylex-group/athena";
 var SDK_HEADER_VALUE = buildSdkHeaderValue(SDK_NAME);
+var NO_CACHE_HEADER_VALUE = "no-cache";
 function parseResponseBody(rawText, contentType) {
   if (!rawText) {
     return { parsed: null, parseFailed: false };
@@ -1916,6 +2036,9 @@ function parseResponseBody(rawText, contentType) {
 function normalizeHeaderValue(value) {
   return value ? value : void 0;
 }
+function isCacheControlHeaderName(name) {
+  return name.toLowerCase() === "cache-control";
+}
 function resolveHeaderValue(headers, candidates) {
   for (const candidate of candidates) {
     const direct = normalizeHeaderValue(headers[candidate]);
@@ -2074,6 +2197,7 @@ function buildRpcGetEndpoint(payload) {
 }
 function buildHeaders(config, options) {
   const mergedStripNulls = options?.stripNulls ?? true;
+  const forceNoCache = Boolean(config.forceNoCache || options?.forceNoCache);
   const extraHeaders = {
     ...config.headers ?? {},
     ...options?.headers ?? {}
@@ -2127,11 +2251,15 @@ function buildHeaders(config, options) {
   const athenaClientKeys = ["x-athena-client", "X-Athena-Client"];
   Object.entries(extraHeaders).forEach(([key, value]) => {
     if (athenaClientKeys.includes(key)) return;
+    if (forceNoCache && isCacheControlHeaderName(key)) return;
     const normalized = normalizeHeaderValue(value);
     if (normalized) {
       headers[key] = normalized;
     }
   });
+  if (forceNoCache) {
+    headers["Cache-Control"] = NO_CACHE_HEADER_VALUE;
+  }
   return headers;
 }
 function toInvalidUrlResponse(error, endpoint, method) {
@@ -2571,6 +2699,35 @@ function quoteSelectColumnsExpression(columns) {
   }
   return tokens.map(quoteSelectToken).join(", ");
 }
+var ATHENA_AUTH_MAX_TEMPLATE_VARIABLES = 64;
+var ATHENA_AUTH_MAX_TEMPLATE_VARIABLE_LENGTH = 128;
+function describeTemplateVariableTarget(target) {
+  const normalized = target?.trim();
+  return normalized && normalized.length > 0 ? normalized : "Athena auth admin email template variables";
+}
+function assertAthenaAuthTemplateVariables(variables, target) {
+  const label = describeTemplateVariableTarget(target);
+  if (!Array.isArray(variables)) {
+    throw new Error(`${label} must be an array of strings.`);
+  }
+  if (variables.length > ATHENA_AUTH_MAX_TEMPLATE_VARIABLES) {
+    throw new Error(
+      `${label} cannot contain more than ${ATHENA_AUTH_MAX_TEMPLATE_VARIABLES} entries.`
+    );
+  }
+  variables.forEach((variable, index) => {
+    if (typeof variable !== "string") {
+      throw new Error(
+        `${label} must contain only strings. Received ${typeof variable} at index ${index}.`
+      );
+    }
+    if (variable.length > ATHENA_AUTH_MAX_TEMPLATE_VARIABLE_LENGTH) {
+      throw new Error(
+        `${label} cannot contain entries longer than ${ATHENA_AUTH_MAX_TEMPLATE_VARIABLE_LENGTH} characters. Received ${variable.length} characters at index ${index}.`
+      );
+    }
+  });
+}
 
 // src/auth/react-email.ts
 var reactEmailRenderModulePromise;
@@ -2760,6 +2917,7 @@ async function resolveReactEmailPayloadFields(input, fields, options) {
 var DEFAULT_AUTH_BASE_URL = "http://localhost:3001/api/auth";
 var SDK_NAME2 = "xylex-group/athena-auth";
 var SDK_HEADER_VALUE2 = buildSdkHeaderValue(SDK_NAME2);
+var NO_CACHE_HEADER_VALUE2 = "no-cache";
 function normalizeBaseUrl(baseUrl) {
   return (baseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/$/, "");
 }
@@ -2769,6 +2927,9 @@ function isRecord4(value) {
 function normalizeHeaderValue2(value) {
   return value ? value : void 0;
 }
+function isCacheControlHeaderName2(name) {
+  return name.toLowerCase() === "cache-control";
+}
 function parseResponseBody2(rawText, contentType) {
   if (!rawText) {
     return { parsed: null, parseFailed: false };
@@ -2824,6 +2985,54 @@ function mergeCallOptions(base, override) {
     }
   };
 }
+function toSessionGuardFailure(sessionResult) {
+  if (sessionResult.status === 401 || sessionResult.data == null) {
+    return {
+      ok: false,
+      reason: "unauthorized",
+      status: 401,
+      error: sessionResult.error ?? "Unauthorized",
+      sessionResult
+    };
+  }
+  return {
+    ok: false,
+    reason: "upstream_error",
+    status: sessionResult.status,
+    error: sessionResult.error ?? "Failed to resolve current session",
+    sessionResult
+  };
+}
+function toPermissionGuardFailure(permissionResult, sessionResult) {
+  if (permissionResult.status === 401) {
+    return {
+      ok: false,
+      reason: "unauthorized",
+      status: 401,
+      error: permissionResult.error ?? "Unauthorized",
+      sessionResult,
+      permissionResult
+    };
+  }
+  if (permissionResult.status === 403) {
+    return {
+      ok: false,
+      reason: "forbidden",
+      status: 403,
+      error: permissionResult.error ?? "Forbidden",
+      sessionResult,
+      permissionResult
+    };
+  }
+  return {
+    ok: false,
+    reason: "upstream_error",
+    status: permissionResult.status,
+    error: permissionResult.error ?? "Failed to resolve permission check",
+    sessionResult,
+    permissionResult
+  };
+}
 function extractFetchOptions(input) {
   if (!input) {
     return {
@@ -2839,6 +3048,7 @@ function extractFetchOptions(input) {
   };
 }
 function buildHeaders2(config, options) {
+  const forceNoCache = Boolean(config.forceNoCache || options?.forceNoCache);
   const headers = {
     "Content-Type": "application/json",
     "X-Athena-Sdk": SDK_HEADER_VALUE2
@@ -2852,16 +3062,30 @@ function buildHeaders2(config, options) {
   if (bearerToken) {
     headers.Authorization = `Bearer ${bearerToken}`;
   }
+  const cookie = options?.cookie ?? config.cookie;
+  if (cookie) {
+    headers.Cookie = cookie;
+  }
+  const sessionToken = options?.sessionToken ?? config.sessionToken;
+  if (sessionToken) {
+    headers["X-Athena-Auth-Session-Token"] = sessionToken;
+  }
   const mergedExtraHeaders = {
     ...config.headers ?? {},
     ...options?.headers ?? {}
   };
   Object.entries(mergedExtraHeaders).forEach(([key, value]) => {
+    if (forceNoCache && isCacheControlHeaderName2(key)) {
+      return;
+    }
     const normalized = normalizeHeaderValue2(value);
     if (normalized) {
       headers[key] = normalized;
     }
   });
+  if (forceNoCache) {
+    headers["Cache-Control"] = NO_CACHE_HEADER_VALUE2;
+  }
   return headers;
 }
 function appendQueryParam(searchParams, key, value) {
@@ -3126,7 +3350,91 @@ function createAuthClient(config = {}) {
     htmlField: "htmlTemplate",
     textField: "textTemplate",
     variablesField: "variables"
-  }, withReactEmailRoute(route));
+  }, withReactEmailRoute(route)).then((payload) => {
+    if ("variables" in payload && payload.variables !== void 0 && payload.variables !== null) {
+      assertAthenaAuthTemplateVariables(
+        payload.variables,
+        `${route} variables`
+      );
+    }
+    return payload;
+  });
+  const requireSession = async (input, options) => {
+    const sessionInput = input?.fetchOptions ? { fetchOptions: input.fetchOptions } : void 0;
+    const sessionResult = await getGeneric(
+      "/get-session",
+      sessionInput,
+      options
+    );
+    if (!sessionResult.ok || sessionResult.data == null) {
+      return toSessionGuardFailure(sessionResult);
+    }
+    return {
+      ok: true,
+      session: sessionResult.data
+    };
+  };
+  const getUser = async (input, options) => {
+    const sessionResult = await getGeneric(
+      "/get-session",
+      input,
+      options
+    );
+    if (!sessionResult.ok) {
+      return {
+        ...sessionResult,
+        data: null
+      };
+    }
+    return {
+      ...sessionResult,
+      data: {
+        user: sessionResult.data?.user ?? null
+      }
+    };
+  };
+  const requirePermission = async (endpoint, input, options) => {
+    const sessionGuard = await requireSession(
+      input?.fetchOptions ? { fetchOptions: input.fetchOptions } : void 0,
+      options
+    );
+    if (!sessionGuard.ok) {
+      return sessionGuard;
+    }
+    const permissionResult = await postGeneric(
+      endpoint,
+      input,
+      options
+    );
+    if (!permissionResult.ok) {
+      return toPermissionGuardFailure(permissionResult, {
+        ok: true,
+        status: 200,
+        data: sessionGuard.session,
+        error: null,
+        errorDetails: null,
+        raw: sessionGuard.session
+      });
+    }
+    if (!permissionResult.data?.success) {
+      return {
+        ok: false,
+        reason: "forbidden",
+        status: 403,
+        error: permissionResult.data?.error ?? "Forbidden",
+        sessionResult: {
+          ok: true,
+          status: 200,
+          data: sessionGuard.session,
+          error: null,
+          errorDetails: null,
+          raw: sessionGuard.session
+        },
+        permissionResult
+      };
+    }
+    return sessionGuard;
+  };
   const listUserEmailsWithFallback = async (input, options) => {
     const primary = await getWithQuery(
       "/email/list",
@@ -3288,6 +3596,7 @@ function createAuthClient(config = {}) {
       input,
       options
     ),
+    requirePermission: (input, options) => requirePermission("/organization/has-permission", input, options),
     invitation: {
       cancel: (input, options) => executePostWithCompatibleInput(
         resolvedConfig,
@@ -3483,6 +3792,8 @@ function createAuthClient(config = {}) {
   };
   const auth = {
     getSession: (input, options) => getGeneric("/get-session", input, options),
+    getUser,
+    requireSession,
     signOut,
     forgetPassword: (input, options) => postGeneric("/forget-password", input, options),
     resetPassword: authResetPassword,
@@ -3577,6 +3888,7 @@ function createAuthClient(config = {}) {
         }
       },
       hasPermission: (input, options) => postGeneric("/admin/has-permission", input, options),
+      requirePermission: (input, options) => requirePermission("/admin/has-permission", input, options),
       apiKey: {
         create: (input, options) => postGeneric("/admin/api-key/create", input, options)
       },
@@ -3728,6 +4040,8 @@ function createAuthClient(config = {}) {
       input,
       options
     ),
+    getUser,
+    requireSession,
     listSessions: (input, options) => executeGetWithCompatibleInput(
       resolvedConfig,
       { endpoint: "/list-sessions", method: "GET" },
@@ -8405,6 +8719,59 @@ function createQueryBuilder(client, formatGatewayResult, experimental, tracer) {
     );
   };
 }
+function normalizeOptionalString2(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalizedValue = value.trim();
+  return normalizedValue ? normalizedValue : void 0;
+}
+function readHeaderBagValue(headers, targetKey) {
+  if (!headers) {
+    return void 0;
+  }
+  if (typeof headers.get === "function") {
+    return normalizeOptionalString2(headers.get(targetKey));
+  }
+  const normalizedTargetKey = targetKey.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== normalizedTargetKey) {
+      continue;
+    }
+    if (typeof value === "string") {
+      return normalizeOptionalString2(value);
+    }
+    return void 0;
+  }
+  return void 0;
+}
+function resolveSessionContextOptions(session, options) {
+  const sessionToken = normalizeOptionalString2(session?.session?.token);
+  const requestCookie = readHeaderBagValue(options?.requestHeaders, "cookie") ?? readHeaderBagValue(options?.headers, "cookie");
+  const authInput = options?.auth;
+  const resolvedUserId = options?.userId !== void 0 ? options.userId : session?.user?.id;
+  const resolvedOrganizationId = options?.organizationId !== void 0 ? options.organizationId : session?.session?.activeOrganizationId;
+  const resolvedBearerToken = authInput?.bearerToken !== void 0 ? authInput.bearerToken : sessionToken;
+  const resolvedSessionToken = authInput?.sessionToken !== void 0 ? authInput.sessionToken : sessionToken;
+  const resolvedCookie = authInput?.cookie !== void 0 ? authInput.cookie : requestCookie;
+  const auth = authInput !== void 0 || resolvedBearerToken !== void 0 || resolvedSessionToken !== void 0 || resolvedCookie !== void 0 ? {
+    ...authInput ?? {},
+    ...resolvedBearerToken !== void 0 ? { bearerToken: resolvedBearerToken } : {},
+    ...resolvedSessionToken !== void 0 ? { sessionToken: resolvedSessionToken } : {},
+    ...resolvedCookie !== void 0 ? { cookie: resolvedCookie } : {},
+    headers: authInput?.headers ? { ...authInput.headers } : void 0
+  } : void 0;
+  if (resolvedUserId === void 0 && resolvedOrganizationId === void 0 && options?.forceNoCache === void 0 && !options?.headers && !auth) {
+    return void 0;
+  }
+  return {
+    userId: resolvedUserId,
+    organizationId: resolvedOrganizationId,
+    forceNoCache: options?.forceNoCache,
+    headers: options?.headers ? { ...options.headers } : void 0,
+    auth
+  };
+}
 function resolveClientServiceBaseUrl(value, label) {
   if (value === void 0 || value === null) {
     return void 0;
@@ -8447,6 +8814,87 @@ function resolveRequiredClientApiKey(value) {
   }
   return normalizedValue;
 }
+function hasHeaderIgnoreCase(headers, targetKey) {
+  const normalizedTargetKey = targetKey.toLowerCase();
+  return Object.keys(headers).some((key) => key.toLowerCase() === normalizedTargetKey);
+}
+function mergeClientHeaders(current, next) {
+  if (!current && !next) {
+    return void 0;
+  }
+  return {
+    ...current ?? {},
+    ...next ?? {}
+  };
+}
+function mergeDefinedObject(current, next) {
+  if (!current && !next) {
+    return void 0;
+  }
+  const merged = {
+    ...current ?? {}
+  };
+  const mutableMerged = merged;
+  for (const [key, value] of Object.entries(next ?? {})) {
+    if (value !== void 0) {
+      mutableMerged[key] = value;
+    }
+  }
+  return merged;
+}
+function mergeAuthClientOptions(current, next) {
+  const merged = mergeDefinedObject(current, next);
+  if (!merged) {
+    return void 0;
+  }
+  const mergedHeaders = mergeClientHeaders(current?.headers, next?.headers);
+  if (mergedHeaders) {
+    merged.headers = mergedHeaders;
+  }
+  return merged;
+}
+function mergeServiceUrlOverrides(current, next) {
+  return mergeDefinedObject(current, next);
+}
+function toClientContextOverrides(context) {
+  if (!context) {
+    return void 0;
+  }
+  return {
+    userId: context.userId,
+    organizationId: context.organizationId,
+    forceNoCache: context.forceNoCache,
+    headers: context.headers,
+    auth: context.auth ? {
+      ...context.auth,
+      headers: context.auth.headers ? { ...context.auth.headers } : void 0
+    } : void 0
+  };
+}
+function mergeClientOverrideOptions(base, overrides) {
+  if (!overrides) {
+    return {
+      ...base,
+      headers: base.headers ? { ...base.headers } : void 0,
+      auth: base.auth ? {
+        ...base.auth,
+        headers: base.auth.headers ? { ...base.auth.headers } : void 0
+      } : void 0,
+      db: base.db ? { ...base.db } : void 0,
+      gateway: base.gateway ? { ...base.gateway } : void 0,
+      storage: base.storage ? { ...base.storage } : void 0
+    };
+  }
+  const merged = mergeDefinedObject(base, overrides) ?? { ...base };
+  return {
+    ...merged,
+    headers: mergeClientHeaders(base.headers, overrides.headers),
+    auth: mergeAuthClientOptions(base.auth, overrides.auth),
+    db: mergeServiceUrlOverrides(base.db, overrides.db),
+    gateway: mergeServiceUrlOverrides(base.gateway, overrides.gateway),
+    storage: mergeServiceUrlOverrides(base.storage, overrides.storage)
+  };
+}
 function normalizeAuthClientConfig(auth, defaultBaseUrl) {
   if (!auth && defaultBaseUrl === void 0) {
     return void 0;
@@ -8456,6 +8904,8 @@ function normalizeAuthClientConfig(auth, defaultBaseUrl) {
     baseUrl,
     apiKey,
     bearerToken,
+    cookie,
+    sessionToken,
     ...rest
   } = auth ?? {};
   const normalized = {
@@ -8474,6 +8924,12 @@ function normalizeAuthClientConfig(auth, defaultBaseUrl) {
   if (typeof bearerToken === "string") {
     normalized.bearerToken = bearerToken;
   }
+  if (typeof cookie === "string") {
+    normalized.cookie = cookie;
+  }
+  if (typeof sessionToken === "string") {
+    normalized.sessionToken = sessionToken;
+  }
   return normalized;
 }
 function resolveCreateClientConfig(config) {
@@ -8487,6 +8943,9 @@ function resolveCreateClientConfig(config) {
     baseUrl: resolvedUrls.dbUrl,
     apiKey: resolveRequiredClientApiKey(config.key),
     client: resolveOptionalClientName(config.client),
+    userId: config.userId,
+    organizationId: config.organizationId,
+    forceNoCache: config.forceNoCache,
     backend: toBackendConfig(config.backend),
     headers: config.headers,
     auth: config.auth,
@@ -8495,23 +8954,39 @@ function resolveCreateClientConfig(config) {
     experimental: config.experimental
   };
 }
-function createClientFromConfig(config) {
+function createClientFromInput(sourceConfig) {
+  return createClientFromConfig(resolveCreateClientConfig(sourceConfig), sourceConfig);
+}
+function createClientFromConfig(config, sourceConfig) {
+  const normalizedAuthConfig = normalizeAuthClientConfig(config.auth, config.authUrl);
   const gatewayHeaders = {
     ...config.headers ?? {}
   };
-  if (config.auth?.bearerToken && gatewayHeaders["X-Athena-Auth-Bearer-Token"] === void 0 && gatewayHeaders["x-athena-auth-bearer-token"] === void 0) {
-    gatewayHeaders["X-Athena-Auth-Bearer-Token"] = config.auth.bearerToken;
+  if (normalizedAuthConfig?.bearerToken && !hasHeaderIgnoreCase(gatewayHeaders, "X-Athena-Auth-Bearer-Token")) {
+    gatewayHeaders["X-Athena-Auth-Bearer-Token"] = normalizedAuthConfig.bearerToken;
+  }
+  if (normalizedAuthConfig?.cookie && !hasHeaderIgnoreCase(gatewayHeaders, "Cookie")) {
+    gatewayHeaders.Cookie = normalizedAuthConfig.cookie;
+  }
+  if (normalizedAuthConfig?.sessionToken && !hasHeaderIgnoreCase(gatewayHeaders, "X-Athena-Auth-Session-Token")) {
+    gatewayHeaders["X-Athena-Auth-Session-Token"] = normalizedAuthConfig.sessionToken;
   }
   const gateway = createAthenaGatewayClient({
     baseUrl: config.baseUrl,
     apiKey: config.apiKey,
     client: config.client,
+    userId: config.userId,
+    organizationId: config.organizationId,
+    forceNoCache: config.forceNoCache,
     backend: config.backend,
     headers: gatewayHeaders
   });
   const formatGatewayResult = createResultFormatter(config.experimental);
   const queryTracer = createQueryTracer(config.experimental);
-  const auth = createAuthClient(normalizeAuthClientConfig(config.auth, config.authUrl));
+  const auth = createAuthClient({
+    ...normalizedAuthConfig ?? {},
+    ...config.forceNoCache ? { forceNoCache: true } : {}
+  });
   function from(tableOrModel, options) {
     if (isAthenaModelTarget(tableOrModel)) {
       if (options?.schema !== void 0) {
@@ -8559,17 +9034,45 @@ function createClientFromConfig(config) {
     queryTracer
   );
   const db = createDbModule({ from, rpc, query });
+  const withContext = (context) => createClientFromInput(
+    mergeClientOverrideOptions(sourceConfig, toClientContextOverrides(context))
+  );
+  const withSession = (session, options) => createClientFromInput(
+    mergeClientOverrideOptions(
+      sourceConfig,
+      toClientContextOverrides(resolveSessionContextOptions(session, options))
+    )
+  );
+  const authWithOptions = (options) => createClientFromInput(mergeClientOverrideOptions(sourceConfig, options));
   const sdkClient = {
     from,
     db,
     rpc,
     query,
     verifyConnection: gateway.verifyConnection,
-    auth: auth.auth
+    auth: auth.auth,
+    withContext,
+    withSession,
+    withOptions: authWithOptions
   };
   if (config.experimental?.athenaStorageBackend) {
+    const storageWithContext = (context) => createClientFromInput(
+      mergeClientOverrideOptions(sourceConfig, toClientContextOverrides(context))
+    );
+    const storageWithSession = (session, options) => createClientFromInput(
+      mergeClientOverrideOptions(
+        sourceConfig,
+        toClientContextOverrides(resolveSessionContextOptions(session, options))
+      )
+    );
+    const storageWithOptions = (options) => createClientFromInput(
+      mergeClientOverrideOptions(sourceConfig, options)
+    );
     const storageClient = {
       ...sdkClient,
+      withContext: storageWithContext,
+      withSession: storageWithSession,
+      withOptions: storageWithOptions,
       storage: createStorageModule(gateway, {
         ...config.experimental.storage,
         ...config.storageUrl ? {
@@ -8584,13 +9087,13 @@ function createClientFromConfig(config) {
 }
 function createClient(configOrUrl, apiKey, options) {
   if (typeof configOrUrl === "string" || configOrUrl === null || configOrUrl === void 0) {
-    return createClientFromConfig(resolveCreateClientConfig({
+    return createClientFromInput({
       url: configOrUrl,
       key: apiKey ?? "",
       ...options
-    }));
+    });
   }
-  return createClientFromConfig(resolveCreateClientConfig(configOrUrl));
+  return createClientFromInput(configOrUrl);
 }
 
 // src/schema/postgres-introspection-core.ts
@@ -9146,16 +9649,25 @@ async function fileExists(path) {
 }
 async function writeArtifacts(files, cwd) {
   const writtenFiles = [];
+  const skippedFiles = [];
   for (const file of files) {
     const absolutePath = path.resolve(cwd, file.path);
     if (!canOverwriteArtifact(file) && await fileExists(absolutePath)) {
+      skippedFiles.push({
+        kind: file.kind,
+        path: file.path,
+        reason: "protected-existing-file"
+      });
       continue;
     }
     await promises.mkdir(path.dirname(absolutePath), { recursive: true });
     await promises.writeFile(absolutePath, file.content, "utf8");
     writtenFiles.push(file.path);
   }
-  return writtenFiles;
+  return {
+    writtenFiles,
+    skippedFiles
+  };
 }
 async function runSchemaGenerator(options = {}) {
   const cwd = options.cwd ?? process.cwd();
@@ -9169,12 +9681,13 @@ async function runSchemaGenerator(options = {}) {
     schemas: resolveProviderSchemas(config.provider)
   });
   const generated = generateArtifactsFromSnapshot(snapshot, config);
-  const writtenFiles = options.dryRun ? [] : await writeArtifacts(generated.files, cwd);
+  const writeResult = options.dryRun ? { writtenFiles: [], skippedFiles: [] } : await writeArtifacts(generated.files, cwd);
   return {
     ...generated,
     configPath,
     config,
-    writtenFiles
+    writtenFiles: writeResult.writtenFiles,
+    skippedFiles: writeResult.skippedFiles
   };
 }
 
@@ -9216,24 +9729,64 @@ function generateUsage() {
     "  athena-js generate --config ./athena.config.ts --dry-run"
   ].join("\n");
 }
-function usesSchemaScopedModelTarget(target) {
-  return /\{schema(?:_[a-z]+)?\}/.test(target);
+function normalizePath2(pathValue) {
+  return pathValue.replace(/\\/g, "/");
+}
+function isLegacyConfigRegistryTarget(target) {
+  return normalizePath2(target) === "athena/config.ts";
+}
+function isFlatSchemaTarget(target) {
+  return normalizePath2(target) === "athena/schema.ts";
+}
+function formatProviderLine(result) {
+  const { provider } = result.config;
+  if (provider.kind === "postgres") {
+    const schemaList = Array.isArray(provider.schemas) ? provider.schemas.join(",") : typeof provider.schemas === "string" ? provider.schemas : "public";
+    const database = provider.database ? ` database=${provider.database}` : "";
+    const backend = provider.mode === "gateway" && provider.backend ? ` backend=${provider.backend}` : "";
+    return `[provider] kind=${provider.kind} mode=${provider.mode}${database}${backend} schemas=${schemaList}`;
+  }
+  const datacenter = provider.datacenter ? ` datacenter=${provider.datacenter}` : "";
+  return `[provider] kind=${provider.kind} mode=${provider.mode} keyspace=${provider.keyspace} contactPoints=${provider.contactPoints.join(",")}${datacenter}`;
+}
+function formatFilterLine(result) {
+  const { includeTables, excludeTables } = result.config.filter;
+  if (includeTables.length === 0 && excludeTables.length === 0) {
+    return void 0;
+  }
+  return `[filter] include=${includeTables.length > 0 ? includeTables.join(",") : "-"} exclude=${excludeTables.length > 0 ? excludeTables.join(",") : "-"}`;
 }
 function formatGeneratorModeLines(result) {
   const lines = [
-    `[mode] format=${result.config.output.format} modelTarget=${result.config.output.targets.model}`
+    `[mode] preset=${result.config.output.preset} format=${result.config.output.format} modelTarget=${result.config.output.targets.model}`,
+    formatProviderLine(result),
+    `[targets] schema=${result.config.output.targets.schema} database=${result.config.output.targets.database} registry=${result.config.output.targets.registry}`
   ];
+  const filterLine = formatFilterLine(result);
+  if (filterLine) {
+    lines.push(filterLine);
+  }
   if (result.config.output.format === "define-model") {
     lines.push(
-      '[note] Zero-style table-builder files are not active. Set output.format="table-builder" or ATHENA_GENERATOR_OUTPUT_FORMAT=table-builder to emit table(...).schema(...).columns(...).primaryKey(...).'
+      '[note] Legacy define-model compatibility output is active. Set output.format="table-builder" or ATHENA_GENERATOR_OUTPUT_FORMAT=table-builder to emit table(...).schema(...).columns(...).primaryKey(...).'
+    );
+  }
+  if (result.config.output.preset === "legacy") {
+    lines.push(
+      '[note] Legacy preset is active. It keeps registry output on athena/config.ts for compatibility; prefer output.preset="athena-direct" for the default safe direct layout.'
     );
   }
   lines.push(
-    "[note] Table-builder generation is stable. experimental.findManyAst only affects runtime findMany(...) transport and does not enable generator table output."
+    "[note] Default generator mode is preset=athena-direct + format=table-builder. experimental.findManyAst only affects runtime findMany(...) transport and does not enable generator table output."
   );
-  if (usesSchemaScopedModelTarget(result.config.output.targets.model)) {
+  if (isLegacyConfigRegistryTarget(result.config.output.targets.registry)) {
     lines.push(
-      '[note] Flat athena/models/*.ts output is opt-in. Set output.targets.model="athena/models/{model_kebab}.ts" or ATHENA_GENERATOR_MODEL_TARGET=athena/models/{model_kebab}.ts; multi-schema collisions are still auto-scoped by schema when needed.'
+      '[warn] Registry target points at athena/config.ts. That file is often a handwritten runtime seam; prefer output.preset="athena-direct" or output.targets.registry="athena/registry.generated.ts" unless you intentionally need legacy compatibility.'
+    );
+  }
+  if (isFlatSchemaTarget(result.config.output.targets.schema)) {
+    lines.push(
+      "[warn] Schema target points at athena/schema.ts. Prefer schema-scoped output such as athena/schemas/{schema_kebab}.ts."
     );
   }
   return lines;
@@ -9320,6 +9873,12 @@ function formatGeneratorError(error, configPath) {
   }
   return new Error(normalizeErrorMessage(error));
 }
+function formatSkippedArtifactLine(artifact) {
+  if (artifact.reason === "protected-existing-file") {
+    return ` [skip] ${artifact.path} (existing ${artifact.kind} artifacts are protected from overwrite; delete or retarget the file to regenerate it)`;
+  }
+  return ` [skip] ${artifact.path}`;
+}
 async function runCLI(argv, runtime = {}) {
   const log = runtime.log ?? console.log;
   const runGenerator = runtime.runGenerator ?? runSchemaGenerator;
@@ -9354,6 +9913,9 @@ async function runCLI(argv, runtime = {}) {
   for (const filePath of result.writtenFiles) {
     log(` - ${filePath}`);
   }
+  for (const artifact of result.skippedFiles) {
+    log(formatSkippedArtifactLine(artifact));
+  }
 }
 
 exports.parseCommand = parseCommand;