@aderis-erp/cli 1.0.13 → 1.0.15

package/dist/lib/api-client.js

@@ -1,6 +1,26 @@
 import axios from 'axios';
-import { getValidToken } from './auth.js';
-import { getBaseUrls, getCurrentContext } from './config.js';
+import { getAuthHeaders } from './auth.js';
+import { getAuthType, getBaseUrls, getCurrentContext } from './config.js';
+/**
+ * Normalize a --sort-by value: comma-separated fields, each optionally suffixed
+ * with `:ASC` or `:DESC`. Fields without an explicit direction default to DESC
+ * when the leaf name ends in `At`, `Date`, or `Time` (dates read newest-first);
+ * everything else defaults to ASC. Returned as an array so axios expands it
+ * into repeated `sortBy=a:ASC&sortBy=b:DESC` params.
+ */
+export function normalizeSortBy(input) {
+    return input
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((part) => {
+        if (part.includes(':'))
+            return part;
+        const leaf = part.split('.').pop() ?? part;
+        const dateLike = /(?:At|Date|Time)$/.test(leaf);
+        return `${part}:${dateLike ? 'DESC' : 'ASC'}`;
+    });
+}
 export class ApiError extends Error {
     status;
     data;
@@ -19,14 +39,15 @@ export async function createApiClient(contextName, options = false) {
     if (!context) {
         throw new Error('No context configured. Run: aderis auth login --new');
     }
-    const token = await getValidToken(context.name);
+    const authHeaders = await getAuthHeaders(context.name);
     const { api: baseURL } = getBaseUrls(context.environment);
     const client = axios.create({
         baseURL,
         headers: {
             Accept: binary ? '*/*' : (acceptAny ? '*/*' : 'application/json'),
-            Authorization: `Bearer ${token}`,
             'Content-Type': 'application/json',
+            // Either `Authorization: Bearer <token>` or `x-api-key: <key>`.
+            ...authHeaders,
         },
         // Serialize arrays as repeated params (key=v1&key=v2) instead of bracket format (key[]=v1)
         paramsSerializer: { indexes: null },
@@ -36,9 +57,13 @@ export async function createApiClient(contextName, options = false) {
     // Response interceptor for error handling
     client.interceptors.response.use((response) => response, (error) => {
         if (error.response) {
-            // Handle 401 with a clear message
+            // Handle 401 with a clear message, pointing at the right remedy for the
+            // context's auth type — re-login only helps OAuth contexts.
             if (error.response.status === 401) {
-                throw new ApiError('Session expired. Please run: aderis auth login', 401, error.response.data);
+                const message = getAuthType(context) === 'api_key'
+                    ? `API key for context "${context.name}" was rejected. Check the key with: aderis config set-api-key --context ${context.name}`
+                    : 'Session expired. Please run: aderis auth login';
+                throw new ApiError(message, 401, error.response.data);
             }
             const message = extractErrorMessage(error.response.data);
             throw new ApiError(message, error.response.status, error.response.data);

package/dist/lib/auth.d.ts

@@ -4,6 +4,14 @@ export declare function login(context: Context, options?: {
 }): Promise<TokenData>;
 export declare function refreshTokens(contextName: string): Promise<TokenData>;
 export declare function getValidToken(contextName: string): Promise<string>;
+/**
+ * Build the auth headers for a context: a bearer token for `oauth2` contexts
+ * (refreshing it first if needed) or `x-api-key` for `api_key` contexts.
+ *
+ * This is the single place that decides how credentials reach the API — callers
+ * should never read `tokens` or `api_key` off a context to build headers.
+ */
+export declare function getAuthHeaders(contextName: string): Promise<Record<string, string>>;
 export declare function testAuth(contextName: string): Promise<{
     email: string;
     name?: string;

package/dist/lib/auth.js

@@ -4,7 +4,7 @@ import * as crypto from 'node:crypto';
 import * as http from 'node:http';
 import { URL, URLSearchParams } from 'node:url';
 import open from 'open';
-import { getBaseUrls, getContext, saveCachedTenants, saveTokens, } from './config.js';
+import { getAuthType, getBaseUrls, getContext, missingCredentialsMessage, saveCachedTenants, saveTokens, } from './config.js';
 function buildValidatedUrl(baseUrl, path) {
     try {
         // Minimal path validation
@@ -132,6 +132,23 @@ function renderAuthPage(type, title, message) {
 </body>
 </html>`;
 }
+/**
+ * Guard for flows that only exist for OAuth contexts (browser login, token
+ * refresh, Frontegg tenant switching). API keys are issued per tenant, so there
+ * is nothing to log into or switch.
+ */
+function requireOAuthContext(context, action) {
+    if (getAuthType(context) === 'api_key') {
+        throw new Error(`${action} requires OAuth. Context "${context.name}" authenticates with an API key, which is already scoped to one tenant.`);
+    }
+}
+/** `client_id` is optional on Context (API-key contexts have none), so OAuth flows must assert it. */
+function requireClientId(context) {
+    if (!context.client_id) {
+        throw new Error(`Context "${context.name}" has no OAuth client ID. Recreate it with: aderis config add`);
+    }
+    return context.client_id;
+}
 function generatePKCE() {
     const verifier = crypto.randomBytes(32).toString('base64url');
     const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
@@ -143,7 +160,7 @@ function generateState() {
 function buildAuthorizeUrl(context, pkce, state, options = {}) {
     const { auth: authUrl } = getBaseUrls(context.environment);
     const url = new URL(`${authUrl}/oauth/authorize`);
-    url.searchParams.set('client_id', context.client_id);
+    url.searchParams.set('client_id', requireClientId(context));
     url.searchParams.set('redirect_uri', REDIRECT_URI);
     url.searchParams.set('response_type', 'code');
     url.searchParams.set('state', state);
@@ -155,6 +172,7 @@ function buildAuthorizeUrl(context, pkce, state, options = {}) {
     return url.toString();
 }
 export async function login(context, options = {}) {
+    requireOAuthContext(context, 'Browser login');
     const pkce = generatePKCE();
     const state = generateState();
     const authorizationUrl = buildAuthorizeUrl(context, pkce, state, options);
@@ -252,7 +270,7 @@ async function exchangeCodeForTokens(context, code, codeVerifier) {
     const { auth: authUrl } = getBaseUrls(context.environment);
     const params = new URLSearchParams();
     params.set('grant_type', 'authorization_code');
-    params.set('client_id', context.client_id);
+    params.set('client_id', requireClientId(context));
     params.set('code', code);
     params.set('redirect_uri', REDIRECT_URI);
     params.set('code_verifier', codeVerifier);
@@ -279,13 +297,14 @@ export async function refreshTokens(contextName) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
+    requireOAuthContext(context, 'Token refresh');
     if (!context.tokens?.refresh_token) {
         throw new Error('No refresh token available. Please login again.');
     }
     const { auth: authUrl } = getBaseUrls(context.environment);
     const params = new URLSearchParams();
     params.set('grant_type', 'refresh_token');
-    params.set('client_id', context.client_id);
+    params.set('client_id', requireClientId(context));
     params.set('refresh_token', context.tokens.refresh_token);
     if (context.client_secret) {
         params.set('client_secret', context.client_secret);
@@ -321,6 +340,9 @@ export async function getValidToken(contextName) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
+    if (getAuthType(context) === 'api_key') {
+        throw new Error(`Context "${contextName}" authenticates with an API key and has no access token. Use getAuthHeaders() instead.`);
+    }
     if (!context.tokens?.access_token) {
         throw new Error('Not logged in. Please run: aderis auth login');
     }
@@ -334,17 +356,36 @@ export async function getValidToken(contextName) {
     }
     return context.tokens.access_token;
 }
+/**
+ * Build the auth headers for a context: a bearer token for `oauth2` contexts
+ * (refreshing it first if needed) or `x-api-key` for `api_key` contexts.
+ *
+ * This is the single place that decides how credentials reach the API — callers
+ * should never read `tokens` or `api_key` off a context to build headers.
+ */
+export async function getAuthHeaders(contextName) {
+    const context = getContext(contextName);
+    if (!context) {
+        throw new Error(`Context "${contextName}" not found`);
+    }
+    if (getAuthType(context) === 'api_key') {
+        if (!context.api_key) {
+            throw new Error(missingCredentialsMessage(context));
+        }
+        return { 'x-api-key': context.api_key };
+    }
+    return { Authorization: `Bearer ${await getValidToken(contextName)}` };
+}
 export async function testAuth(contextName) {
     const context = getContext(contextName);
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
-    const token = await getValidToken(contextName);
     const { api: apiUrl } = getBaseUrls(context.environment);
     const response = await axios.get(buildValidatedUrl(apiUrl, '/v1/auth/me'), {
         headers: {
             Accept: 'application/json',
-            Authorization: `Bearer ${token}`,
+            ...(await getAuthHeaders(contextName)),
         },
     });
     return response.data;
@@ -354,6 +395,7 @@ export async function listTenants(contextName) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
+    requireOAuthContext(context, 'Listing tenants');
     const token = await getValidToken(contextName);
     const { auth: authUrl } = getBaseUrls(context.environment);
     let response;
@@ -389,7 +431,8 @@ export async function getCurrentTenant(contextName) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
-    if (!context.tokens?.access_token) {
+    // API-key contexts carry no JWT, so there is no tenant to decode locally.
+    if (getAuthType(context) === 'api_key' || !context.tokens?.access_token) {
         return null;
     }
     const decoded = jwt.decode(context.tokens.access_token);
@@ -415,6 +458,7 @@ export async function switchTenant(contextName, tenantId) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
+    requireOAuthContext(context, 'Switching tenants');
     if (!context.tokens?.refresh_token) {
         throw new Error('No refresh token available. Please login again.');
     }

package/dist/lib/base-api-command.js

@@ -1,11 +1,13 @@
 import { Command, Flags } from '@oclif/core';
 import { ApiError, apiRequest } from './api-client.js';
-import { getCurrentContext } from './config.js';
+import { getCurrentContext, hasCredentials, missingCredentialsMessage } from './config.js';
 export class BaseApiCommand extends Command {
     static globalFlags = {
         context: Flags.string({
+            aliases: ['config'],
             char: 'c',
-            description: 'Context to use (defaults to current context)',
+            description: 'Context to use, overriding the current context (alias: --config)',
+            env: 'ADERIS_CONTEXT',
         }),
         output: Flags.string({
             char: 'o',
@@ -66,8 +68,8 @@ export class BaseApiCommand extends Command {
         if (!context) {
             this.error('No context configured. Run: aderis auth login --new');
         }
-        if (!context.tokens) {
-            this.error(`Not logged in to context "${context.name}". Run: aderis auth login`);
+        if (!hasCredentials(context)) {
+            this.error(missingCredentialsMessage(context));
         }
     }
     printTable(data) {

package/dist/lib/config.d.ts

@@ -1,5 +1,15 @@
 import Conf from 'conf';
 export type Environment = 'dev' | 'live' | 'staging';
+/**
+ * How a context authenticates against the API.
+ *
+ * - `oauth2`: browser PKCE login, sends `Authorization: Bearer <access_token>`
+ * - `api_key`: a long-lived key, sends `x-api-key: <key>`
+ *
+ * Contexts created before API-key support have no `auth_type` field; they are
+ * treated as `oauth2`, so always read it through {@link getAuthType}.
+ */
+export type AuthType = 'api_key' | 'oauth2';
 export interface BaseUrls {
     api: string;
     auth: string;
@@ -17,8 +27,11 @@ export interface CachedTenant {
     tenantId: string;
 }
 export interface Context {
+    api_key?: string;
+    auth_type?: AuthType;
     cachedTenants?: CachedTenant[];
-    client_id: string;
+    /** Only required for `oauth2` contexts; API-key contexts have no OAuth client. */
+    client_id?: string;
     client_secret?: string;
     environment: Environment;
     name: string;
@@ -44,5 +57,22 @@ export declare function saveCachedTenants(contextName: string, tenants: CachedTe
 export declare function getCachedTenants(contextName: string): CachedTenant[] | undefined;
 export declare function getTokens(contextName: string): null | TokenData;
 export declare function clearTokens(contextName: string): void;
+export declare function saveApiKey(contextName: string, apiKey: string): void;
+export declare function clearApiKey(contextName: string): void;
+/**
+ * Auth type of a context, defaulting to `oauth2` for contexts stored before
+ * API-key support existed.
+ */
+export declare function getAuthType(context: Context): AuthType;
+/** Whether a context holds the credential its auth type needs to call the API. */
+export declare function hasCredentials(context: Context): boolean;
+/**
+ * The error to show when a context can't authenticate. Kept here so every
+ * command — including the ~60 generated ones — points at the right remedy for
+ * the context's auth type instead of always suggesting `auth login`.
+ */
+export declare function missingCredentialsMessage(context: Context): string;
+/** Redact a key for display: first and last 4 characters only. */
+export declare function maskApiKey(apiKey: string): string;
 export declare function getBaseUrls(environment: Environment): BaseUrls;
 export { config };

package/dist/lib/config.js

@@ -133,6 +133,37 @@ export function getTokens(contextName) {
 export function clearTokens(contextName) {
     updateContext(contextName, { tokens: undefined });
 }
+export function saveApiKey(contextName, apiKey) {
+    updateContext(contextName, { api_key: apiKey, auth_type: 'api_key' });
+}
+export function clearApiKey(contextName) {
+    updateContext(contextName, { api_key: undefined });
+}
+/**
+ * Auth type of a context, defaulting to `oauth2` for contexts stored before
+ * API-key support existed.
+ */
+export function getAuthType(context) {
+    return context.auth_type ?? 'oauth2';
+}
+/** Whether a context holds the credential its auth type needs to call the API. */
+export function hasCredentials(context) {
+    return getAuthType(context) === 'api_key' ? Boolean(context.api_key) : Boolean(context.tokens);
+}
+/**
+ * The error to show when a context can't authenticate. Kept here so every
+ * command — including the ~60 generated ones — points at the right remedy for
+ * the context's auth type instead of always suggesting `auth login`.
+ */
+export function missingCredentialsMessage(context) {
+    return getAuthType(context) === 'api_key'
+        ? `No API key set for context "${context.name}". Run: aderis config set-api-key --context ${context.name}`
+        : `Not logged in to context "${context.name}". Run: aderis auth login --context ${context.name}`;
+}
+/** Redact a key for display: first and last 4 characters only. */
+export function maskApiKey(apiKey) {
+    return apiKey.length <= 8 ? '*'.repeat(apiKey.length) : `${apiKey.slice(0, 4)}${'*'.repeat(8)}${apiKey.slice(-4)}`;
+}
 export function getBaseUrls(environment) {
     return BASE_URLS[environment];
 }