@xylex-group/athena 1.6.2 → 1.9.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.6.2`
+current version: `1.9.0`
 `@xylex-group/athena` is a database driver and API gateway SDK that lets you interact with SQL backends over HTTP through a fluent builder API. It ships a typed query builder for Node.js / server environments plus Athena-native React hooks for client-side use.
 
 ## Install
@@ -43,6 +43,51 @@ if (error) {
 }
 ```
 
+### Auth client (Athena Auth server)
+
+If your auth backend is now Athena Auth, you can keep core login/session flows in this SDK:
+
+```ts
+import { createAuthClient } from "@xylex-group/athena";
+
+const auth = createAuthClient({
+  baseUrl: "http://localhost:3001/api/auth",
+  // optional: bearer token if you are not using cookie-based sessions
+  bearerToken: process.env.AUTH_BEARER_TOKEN,
+});
+
+const login = await auth.signIn.email({
+  email: "demo@example.com",
+  password: "super-secret",
+  rememberMe: true,
+});
+
+const session = await auth.getSession();
+const sessions = await auth.listSessions();
+
+// clear one session
+await auth.revokeSession({ token: "session_token_here" });
+// or clear all sessions
+await auth.revokeSessions();
+
+await auth.signOut();
+
+// additional core flows
+await auth.forgetPassword({ email: "demo@example.com", redirectTo: "https://app/reset-password" });
+await auth.resetPassword({ newPassword: "new-secret", token: "reset_token" });
+await auth.verifyEmail({ token: "verify_token", callbackURL: "https://app/verified" });
+await auth.changePassword({ currentPassword: "old-secret", newPassword: "new-secret" });
+await auth.updateUser({ name: "Demo User" });
+
+// escape hatch for any endpoint on your Athena Auth instance
+await auth.request({
+  endpoint: "/ok",
+  query: { ping: "pong" },
+});
+```
+
+Auth responses follow the same envelope style: `{ ok, status, data, error, errorDetails, raw }`.
+
 ### Typed schema registry (model-first)
 
 You can keep `createClient(...).from<T>(...)` as-is, or opt into a typed registry:
@@ -101,6 +146,7 @@ Generator supports:
 
 - PostgreSQL direct introspection (`provider.mode = "direct"`, `provider.connectionString` from your `PG_URL`/`DATABASE_URL`)
 - PostgreSQL gateway-only introspection (`provider.mode = "gateway"` via Athena `POST /gateway/query`)
+- Multiple schema syncs such as `public` plus `athena`, with schema-safe default output paths
 - Placeholder-driven output paths
 - Feature flags (`features.emitRegistry`, `features.emitRelations`)
 
@@ -344,11 +390,23 @@ const { data: user } = await athena
   .single();
 ```
 
-`maybeSingle` behaves identically — both return the first element of the result set.
-
-### RPC
-
-Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
+`maybeSingle` behaves identically — both return the first element of the result set.
+
+### Table schema targeting
+
+Use `schema` in table call options to qualify unqualified table names:
+
+```ts
+const { data } = await athena
+  .from("users")
+  .select("id,email", { schema: "public" });
+```
+
+This resolves the table target to `public.users`.
+
+### RPC
+
+Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
 
 ```ts
 const { data, count } = await athena
@@ -382,11 +440,12 @@ RPC options: `schema`, `count` (`"exact" | "planned" | "estimated"`), `head`, `g
 
 Pass options as the second argument to `.select()`:
 
-| Option       | Type                                  | Description                                  |
-| ------------ | ------------------------------------- | -------------------------------------------- |
-| `count`      | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data       |
-| `head`       | `boolean`                             | return response headers only (no rows)       |
-| `stripNulls` | `boolean`                             | strip null values from rows (default `true`) |
+| Option       | Type                                  | Description                                  |
+| ------------ | ------------------------------------- | -------------------------------------------- |
+| `schema`     | `string`                              | qualify unqualified table names for table calls |
+| `count`      | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data       |
+| `head`       | `boolean`                             | return response headers only (no rows)       |
+| `stripNulls` | `boolean`                             | strip null values from rows (default `true`) |
 
 ```ts
 const { data } = await athena

package/dist/cli/index.cjs

@@ -291,6 +291,37 @@ function resolvePostgresColumnType(column) {
   }
   return wrapArrayType(baseType, column.arrayDimensions);
 }
+
+// src/generator/schema-selection.ts
+var DEFAULT_POSTGRES_SCHEMAS = ["public"];
+function collectSchemaNames(input) {
+  if (!input) {
+    return [];
+  }
+  const values = typeof input === "string" ? [input] : input;
+  return values.flatMap((value) => String(value).split(","));
+}
+function normalizeSchemaSelection(input) {
+  const schemas = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of collectSchemaNames(input)) {
+    const schema = value.trim();
+    if (!schema || seen.has(schema)) {
+      continue;
+    }
+    seen.add(schema);
+    schemas.push(schema);
+  }
+  return schemas.length > 0 ? schemas : [...DEFAULT_POSTGRES_SCHEMAS];
+}
+function resolveProviderSchemas(providerConfig) {
+  if (providerConfig.kind === "postgres") {
+    return normalizeSchemaSelection(providerConfig.schemas);
+  }
+  return [...DEFAULT_POSTGRES_SCHEMAS];
+}
+
+// src/generator/config.ts
 var DEFAULT_CONFIG_CANDIDATES = [
   "athena.config.ts",
   "athena.config.js",
@@ -300,8 +331,8 @@ var DEFAULT_CONFIG_CANDIDATES = [
   ".athena.config.js"
 ];
 var DEFAULT_TARGETS = {
-  model: "athena/models/{model_kebab}.ts",
-  schema: "athena/schema.ts",
+  model: "athena/models/{schema_kebab}/{model_kebab}.ts",
+  schema: "athena/schemas/{schema_kebab}.ts",
   database: "athena/relations.ts",
   registry: "athena/config.ts"
 };
@@ -331,6 +362,15 @@ function normalizeOutputConfig(output) {
     }
   };
 }
+function normalizeProviderConfig(provider) {
+  if (provider.kind === "postgres") {
+    return {
+      ...provider,
+      schemas: normalizeSchemaSelection(provider.schemas)
+    };
+  }
+  return provider;
+}
 function isAthenaGeneratorConfig(value) {
   if (!value || typeof value !== "object") {
     return false;
@@ -340,7 +380,7 @@ function isAthenaGeneratorConfig(value) {
 }
 function normalizeGeneratorConfig(input) {
   return {
-    provider: input.provider,
+    provider: normalizeProviderConfig(input.provider),
     output: normalizeOutputConfig(input.output),
     naming: {
       ...DEFAULT_NAMING,
@@ -550,12 +590,19 @@ export const ${registryConstName} = defineRegistry({
   };
 }
 function assertNoDuplicatePaths(files) {
-  const seen = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Map();
   for (const file of files) {
-    if (seen.has(file.path)) {
-      throw new Error(`Generator output collision detected for path: ${file.path}`);
+    const existing = seen.get(file.path);
+    if (existing) {
+      throw new Error(
+        [
+          `Generator output collision detected for path: ${file.path}`,
+          `Collision: ${existing.kind} and ${file.kind}.`,
+          "When syncing multiple schemas, include a schema placeholder such as {schema} or {schema_kebab} in model/schema output targets."
+        ].join(" ")
+      );
     }
-    seen.add(file.path);
+    seen.set(file.path, file);
   }
 }
 var ArtifactComposer = class {
@@ -1184,6 +1231,12 @@ function mergeOptions(...options) {
     return { ...acc, ...next };
   }, void 0);
 }
+function asAthenaJsonObject(value) {
+  return value;
+}
+function asAthenaJsonObjectArray(values) {
+  return values;
+}
 function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS) {
   let selectedColumns = defaultColumns === null ? void 0 : defaultColumns;
   let selectedOptions;
@@ -1272,6 +1325,22 @@ function buildSelectColumnsClause(columns) {
   }
   return quoteSelectColumnsExpression(columns);
 }
+function resolveTableNameForCall(tableName, schema) {
+  if (!schema) return tableName;
+  const normalizedSchema = schema.trim();
+  if (!normalizedSchema) {
+    throw new Error("schema option must be a non-empty string");
+  }
+  if (tableName.includes(".")) {
+    if (tableName.startsWith(`${normalizedSchema}.`)) {
+      return tableName;
+    }
+    throw new Error(
+      `schema option "${normalizedSchema}" conflicts with schema-qualified table "${tableName}"`
+    );
+  }
+  return `${normalizedSchema}.${tableName}`;
+}
 function conditionToSqlClause(condition) {
   if (!condition.column) return null;
   const column = withCast(quoteQualifiedIdentifier(condition.column), condition.column_cast);
@@ -1351,23 +1420,27 @@ function buildTypedSelectQuery(input) {
 function createFilterMethods(state, addCondition, self) {
   return {
     eq(column, value) {
-      if (shouldUseUuidTextComparison(column, value)) {
-        addCondition("eq", column, value, { columnCast: "text" });
+      const columnName = String(column);
+      if (shouldUseUuidTextComparison(columnName, value)) {
+        addCondition("eq", columnName, value, { columnCast: "text" });
       } else {
-        addCondition("eq", column, value);
+        addCondition("eq", columnName, value);
       }
       return self;
     },
     eqCast(column, value, cast) {
-      addCondition("eq", column, value, { valueCast: cast });
+      addCondition("eq", String(column), value, { valueCast: cast });
       return self;
     },
     eqUuid(column, value) {
-      addCondition("eq", column, value, { valueCast: "uuid" });
+      addCondition("eq", String(column), value, { valueCast: "uuid" });
       return self;
     },
     match(filters) {
       Object.entries(filters).forEach(([column, value]) => {
+        if (value === void 0) {
+          return;
+        }
         if (shouldUseUuidTextComparison(column, value)) {
           addCondition("eq", column, value, { columnCast: "text" });
         } else {
@@ -1403,60 +1476,61 @@ function createFilterMethods(state, addCondition, self) {
     },
     order(column, options) {
       state.order = {
-        field: column,
+        field: String(column),
         direction: options?.ascending === false ? "descending" : "ascending"
       };
       return self;
     },
     gt(column, value) {
-      addCondition("gt", column, value);
+      addCondition("gt", String(column), value);
       return self;
     },
     gte(column, value) {
-      addCondition("gte", column, value);
+      addCondition("gte", String(column), value);
       return self;
     },
     lt(column, value) {
-      addCondition("lt", column, value);
+      addCondition("lt", String(column), value);
       return self;
     },
     lte(column, value) {
-      addCondition("lte", column, value);
+      addCondition("lte", String(column), value);
       return self;
     },
     neq(column, value) {
-      addCondition("neq", column, value);
+      addCondition("neq", String(column), value);
       return self;
     },
     like(column, value) {
-      addCondition("like", column, value);
+      addCondition("like", String(column), value);
       return self;
     },
     ilike(column, value) {
-      addCondition("ilike", column, value);
+      addCondition("ilike", String(column), value);
       return self;
     },
     is(column, value) {
-      addCondition("is", column, value);
+      addCondition("is", String(column), value);
       return self;
     },
     in(column, values) {
-      addCondition("in", column, values);
+      addCondition("in", String(column), values);
       return self;
     },
     contains(column, values) {
-      addCondition("contains", column, values);
+      addCondition("contains", String(column), values);
       return self;
     },
     containedBy(column, values) {
-      addCondition("containedBy", column, values);
+      addCondition("containedBy", String(column), values);
       return self;
     },
     not(columnOrExpression, operator, value) {
+      const expression = String(columnOrExpression);
       if (operator != null && value !== void 0) {
-        addCondition("not", void 0, `${columnOrExpression}.${operator}.${stringifyFilterValue(value)}`);
+        addCondition("not", void 0, `${expression}.${operator}.${stringifyFilterValue(value)}`);
       } else {
-        addCondition("not", void 0, columnOrExpression);
+        addCondition("not", void 0, expression);
       }
       return self;
     },
@@ -1626,15 +1700,20 @@ function createTableBuilder(tableName, client) {
     state.conditions.push(condition);
   };
   const builder = {};
-  const filterMethods = createFilterMethods(state, addCondition, builder);
+  const filterMethods = createFilterMethods(
+    state,
+    addCondition,
+    builder
+  );
   const runSelect = async (columns = DEFAULT_COLUMNS, options) => {
+    const resolvedTableName = resolveTableNameForCall(tableName, options?.schema);
     const conditions = state.conditions.length ? state.conditions.map((condition) => ({ ...condition })) : void 0;
     const hasTypedEqualityComparison = conditions?.some(
       (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
     ) ?? false;
     if (hasTypedEqualityComparison && !options?.head && !options?.count && conditions) {
       const query = buildTypedSelectQuery({
-        tableName,
+        tableName: resolvedTableName,
         columns,
         conditions,
         limit: state.limit,
@@ -1649,7 +1728,7 @@ function createTableBuilder(tableName, client) {
       }
     }
     const payload = {
-      table_name: tableName,
+      table_name: resolvedTableName,
       columns,
       conditions,
       limit: state.limit,
@@ -1706,9 +1785,10 @@ function createTableBuilder(tableName, client) {
       if (Array.isArray(values)) {
         const executeInsertMany = async (columns, selectOptions) => {
           const mergedOptions = mergeOptions(options, selectOptions);
+          const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
           const payload = {
-            table_name: tableName,
-            insert_body: values
+            table_name: resolvedTableName,
+            insert_body: asAthenaJsonObjectArray(values)
           };
           if (columns) payload.columns = columns;
           if (mergedOptions?.count) payload.count = mergedOptions.count;
@@ -1723,9 +1803,10 @@ function createTableBuilder(tableName, client) {
       }
       const executeInsertOne = async (columns, selectOptions) => {
         const mergedOptions = mergeOptions(options, selectOptions);
+        const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
-          table_name: tableName,
-          insert_body: values
+          table_name: resolvedTableName,
+          insert_body: asAthenaJsonObject(values)
         };
         if (columns) payload.columns = columns;
         if (mergedOptions?.count) payload.count = mergedOptions.count;
@@ -1742,10 +1823,11 @@ function createTableBuilder(tableName, client) {
       if (Array.isArray(values)) {
         const executeUpsertMany = async (columns, selectOptions) => {
           const mergedOptions = mergeOptions(options, selectOptions);
+          const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
           const payload = {
-            table_name: tableName,
-            insert_body: values,
-            update_body: options?.updateBody ? options.updateBody : void 0
+            table_name: resolvedTableName,
+            insert_body: asAthenaJsonObjectArray(values),
+            update_body: options?.updateBody ? asAthenaJsonObject(options.updateBody) : void 0
           };
           if (columns) payload.columns = columns;
           if (options?.onConflict) payload.on_conflict = options.onConflict;
@@ -1761,10 +1843,11 @@ function createTableBuilder(tableName, client) {
       }
       const executeUpsertOne = async (columns, selectOptions) => {
         const mergedOptions = mergeOptions(options, selectOptions);
+        const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
-          table_name: tableName,
-          insert_body: values,
-          update_body: options?.updateBody ? options.updateBody : void 0
+          table_name: resolvedTableName,
+          insert_body: asAthenaJsonObject(values),
+          update_body: options?.updateBody ? asAthenaJsonObject(options.updateBody) : void 0
         };
         if (columns) payload.columns = columns;
         if (options?.onConflict) payload.on_conflict = options.onConflict;
@@ -1782,9 +1865,10 @@ function createTableBuilder(tableName, client) {
       const executeUpdate = async (columns, selectOptions) => {
         const filters = state.conditions.length ? [...state.conditions] : void 0;
         const mergedOptions = mergeOptions(options, selectOptions);
+        const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
-          table_name: tableName,
-          set: values,
+          table_name: resolvedTableName,
+          set: asAthenaJsonObject(values),
           conditions: filters,
           strip_nulls: mergedOptions?.stripNulls ?? true
         };
@@ -1810,8 +1894,9 @@ function createTableBuilder(tableName, client) {
       }
       const executeDelete = async (columns, selectOptions) => {
         const mergedOptions = mergeOptions(options, selectOptions);
+        const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
-          table_name: tableName,
+          table_name: resolvedTableName,
           resource_id: resourceId,
           conditions: filters
         };
@@ -2111,8 +2196,21 @@ function coerceStringArray(value) {
   }
   return [];
 }
+function normalizePostgresCatalogSchemas(schemas) {
+  const normalized = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of schemas ?? []) {
+    const schema = value.trim();
+    if (!schema || seen.has(schema)) {
+      continue;
+    }
+    seen.add(schema);
+    normalized.push(schema);
+  }
+  return normalized.length > 0 ? normalized : ["public"];
+}
 function buildSchemaArrayLiteral(schemas) {
-  const normalized = schemas.length > 0 ? schemas : ["public"];
+  const normalized = normalizePostgresCatalogSchemas(schemas);
   const literals = normalized.map((schema) => `'${escapeSqlLiteral(schema)}'`).join(", ");
   return `ARRAY[${literals}]`;
 }
@@ -2311,12 +2409,14 @@ var PostgresIntrospectionProvider = class {
   backend = "postgresql";
   connectionString;
   database;
+  schemas;
   constructor(options) {
     this.connectionString = options.connectionString;
     this.database = options.database ?? "postgres";
+    this.schemas = normalizePostgresCatalogSchemas(options.schemas);
   }
   async inspect(options) {
-    const schemas = options?.schemas && options.schemas.length > 0 ? options.schemas : ["public"];
+    const schemas = options?.schemas && options.schemas.length > 0 ? normalizePostgresCatalogSchemas(options.schemas) : this.schemas;
     const pool = new pg.Pool({
       connectionString: this.connectionString
     });
@@ -2388,11 +2488,13 @@ var AthenaGatewayPostgresIntrospectionProvider = class {
         type: this.config.backend ?? "postgresql"
       }
     });
+    this.schemas = normalizeSchemaSelection(this.config.schemas);
   }
   backend = "postgresql";
   client;
+  schemas;
   async inspect(options) {
-    const schemas = options?.schemas && options.schemas.length > 0 ? options.schemas : this.config.schemas && this.config.schemas.length > 0 ? this.config.schemas : ["public"];
+    const schemas = options?.schemas && options.schemas.length > 0 ? normalizeSchemaSelection(options.schemas) : this.schemas;
     const catalogClient = new AthenaGatewayCatalogClient(this.client);
     const queries = buildGatewayCatalogQueries(schemas);
     const [columnRows, enumMap, primaryKeyRows, foreignKeyRows] = await Promise.all([
@@ -2428,7 +2530,8 @@ var ScyllaIntrospectionProvider = class {
 function createPostgresProvider(config) {
   return createPostgresIntrospectionProvider({
     connectionString: config.connectionString,
-    database: config.database
+    database: config.database,
+    schemas: normalizeSchemaSelection(config.schemas)
   });
 }
 function resolveGeneratorProvider(providerConfig, experimentalFlags) {
@@ -2450,12 +2553,6 @@ function resolveGeneratorProvider(providerConfig, experimentalFlags) {
 }
 
 // src/generator/pipeline.ts
-function extractProviderSchemas(providerConfig) {
-  if (!("schemas" in providerConfig) || !providerConfig.schemas || providerConfig.schemas.length === 0) {
-    return void 0;
-  }
-  return providerConfig.schemas;
-}
 async function writeArtifacts(files, cwd) {
   const writtenFiles = [];
   for (const file of files) {
@@ -2475,7 +2572,7 @@ async function runSchemaGenerator(options = {}) {
   const { configPath, config } = await loadGeneratorConfig(configOptions);
   const provider = options.provider ?? resolveGeneratorProvider(config.provider, config.experimental);
   const snapshot = await provider.inspect({
-    schemas: extractProviderSchemas(config.provider)
+    schemas: resolveProviderSchemas(config.provider)
   });
   const generated = generateArtifactsFromSnapshot(snapshot, config);
   const writtenFiles = options.dryRun ? [] : await writeArtifacts(generated.files, cwd);