@grantjs/cli 1.11.0 → 1.13.0

package/README.md

@@ -1,6 +1,6 @@
 # @grantjs/cli
 
-Grant CLI for setup, authentication, profiles, and typings generation.
+Grant CLI for profiles, REST API access, and typings generation. Agents and scripts should use `grant api` or `grant <resource> <verb>` with `--output json` (or `GRANT_*` environment variables).
 
 ## Install
 
@@ -17,13 +17,25 @@ npm install -g @grantjs/cli
 | `grant version`               | Show CLI version (`-j, --json` for JSON)                                                       |
 | `grant help` / `grant --help` | Show help                                                                                      |
 | `grant start`                 | Interactive setup (API URL, auth, profile, scope); alias: `grant setup`                        |
+| `grant whoami`                | Show the authenticated caller (`GET /api/me`)                                                  |
+| `grant api <method> <path>`   | Call any REST path with the resolved profile                                                   |
+| `grant <resource> <verb>`     | Named REST commands from OpenAPI (e.g. `grant users list`)                                     |
 | `grant generate-types`        | Generate project-scoped `ResourceSlug` and `ResourceAction` TypeScript (uses selected profile) |
 | `grant config path`           | Print path to the config file                                                                  |
 | `grant config list`           | List profiles and which is default                                                             |
 | `grant config show`           | Show config summary for a profile (no secrets)                                                 |
 | `grant config set <key>`      | Set a config value for a profile (see below)                                                   |
 
-All commands that use config accept **`-p, --profile <name>`** to target a profile (default: the configured default profile).
+All commands that use config accept **`-p, --profile <name>`** (or `GRANT_PROFILE`). API commands also accept `--output json|text` (JSON when stdout is not a TTY).
+
+Environment: `GRANT_API_URL`, `GRANT_ACCESS_TOKEN`, `GRANT_CLIENT_ID`, `GRANT_CLIENT_SECRET`, `GRANT_SCOPE_TENANT`, `GRANT_SCOPE_ID`, `GRANT_ORIGIN_VERIFY`. Flags win over env, env over the profile file.
+
+```bash
+export GRANT_PROFILE=ci
+grant whoami --output json
+grant users list --output json
+grant api post /api/roles --body '{"name":"Reviewer"}'
+```
 
 ---
 
@@ -99,6 +111,7 @@ Set a value for a profile. Use **`-p, --profile <name>`** to target a profile (d
 | `grant config set credentials`                      | Set API key and scope (see options below)                           |
 | `grant config set scope`                            | Set selected project scope only                                     |
 | `grant config set generate-types-output <path>`     | Set default output path for `grant generate-types` (empty to clear) |
+| `grant config set origin-verify [secret]`           | Set `x-origin-verify` when `apiUrl` is the raw API origin           |
 | `grant config set default-profile <name>`           | Set which profile is used when `--profile` is omitted               |
 
 **Credentials options** (all required for `credentials`):

package/dist/api/authenticated.d.ts

@@ -0,0 +1,11 @@
+import { RuntimeFlags } from '../config/credentials.js';
+import { TransportResponse } from './transport.js';
+export interface AuthenticatedRequest {
+    flags?: RuntimeFlags;
+    method: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    injectScope?: boolean;
+}
+export declare function authenticatedRequest<T = unknown>(req: AuthenticatedRequest): Promise<TransportResponse<T>>;

package/dist/api/client.d.ts

@@ -45,6 +45,13 @@ export interface ProjectItem {
  * POST {baseUrl}/api/auth/token
  */
 export declare function exchangeApiKey(baseUrl: string, body: TokenExchangeRequest): Promise<TokenExchangeResponse>;
+/**
+ * Refresh a session. Cookie is preferred by browsers; CLI sends the stored refresh token in the body.
+ */
+export declare function refreshSession(baseUrl: string, refreshToken: string, originVerifySecret?: string): Promise<{
+    accessToken: string;
+    refreshToken?: string;
+}>;
 /**
  * Login with email and password. POST {baseUrl}/api/auth/login
  * Returns access token, refresh token, and primary account (personal).
@@ -59,12 +66,12 @@ export declare function exchangeCliCallback(baseUrl: string, code: string): Prom
  * Fetch organizations (paginated). Requires Bearer token. GET /api/organizations?scopeId=&tenant=
  * Scope is the account context (user's personal account id, tenant 'account').
  */
-export declare function fetchOrganizations(baseUrl: string, accessToken: string, scope: ApiScope): Promise<OrganizationItem[]>;
+export declare function fetchOrganizations(baseUrl: string, accessToken: string, scope: ApiScope, originVerifySecret?: string): Promise<OrganizationItem[]>;
 /**
  * Fetch projects for a scope (account or organization). Paginated. Requires Bearer token.
  * GET /api/projects?scopeId=&tenant=
  */
-export declare function fetchProjects(baseUrl: string, accessToken: string, scope: ApiScope): Promise<ProjectItem[]>;
+export declare function fetchProjects(baseUrl: string, accessToken: string, scope: ApiScope, originVerifySecret?: string): Promise<ProjectItem[]>;
 export interface ApiScope {
     id: string;
     tenant: string;
@@ -85,9 +92,9 @@ export interface PermissionItem {
 /**
  * Fetch all resources for a scope (paginated). Requires Bearer token.
  */
-export declare function fetchResources(baseUrl: string, accessToken: string, scope: ApiScope): Promise<ResourceItem[]>;
+export declare function fetchResources(baseUrl: string, accessToken: string, scope: ApiScope, originVerifySecret?: string): Promise<ResourceItem[]>;
 /**
  * Fetch all permissions for a scope (paginated). Requires Bearer token.
  */
-export declare function fetchPermissions(baseUrl: string, accessToken: string, scope: ApiScope): Promise<PermissionItem[]>;
+export declare function fetchPermissions(baseUrl: string, accessToken: string, scope: ApiScope, originVerifySecret?: string): Promise<PermissionItem[]>;
 export {};

package/dist/api/errors.d.ts

@@ -0,0 +1,9 @@
+/** Process exit codes. 0 is success (Commander default). */
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_AUTH = 2;
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare function isAuthFailure(status: number, message: string): boolean;
+export declare function handleCliError(err: unknown): never;

package/dist/api/transport.d.ts

@@ -0,0 +1,15 @@
+export interface TransportRequest {
+    apiUrl: string;
+    method: string;
+    path: string;
+    token?: string;
+    originVerifySecret?: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    extraHeaders?: Record<string, string>;
+}
+export interface TransportResponse<T = unknown> {
+    status: number;
+    data: T;
+}
+export declare function apiRequest<T = unknown>(req: TransportRequest): Promise<TransportResponse<T>>;

package/dist/commands/api.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createApiCommand(program: Command): void;

package/dist/commands/from-spec.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createSpecCommands(program: Command): void;

package/dist/commands/whoami.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createWhoamiCommand(program: Command): void;

package/dist/config/credentials.d.ts

@@ -0,0 +1,29 @@
+import { GrantConfig, GrantScope } from '../types/config.js';
+export declare const ENV: {
+    readonly profile: "GRANT_PROFILE";
+    readonly apiUrl: "GRANT_API_URL";
+    readonly clientId: "GRANT_CLIENT_ID";
+    readonly clientSecret: "GRANT_CLIENT_SECRET";
+    readonly scopeTenant: "GRANT_SCOPE_TENANT";
+    readonly scopeId: "GRANT_SCOPE_ID";
+    readonly originVerify: "GRANT_ORIGIN_VERIFY";
+    readonly accessToken: "GRANT_ACCESS_TOKEN";
+};
+export interface RuntimeFlags {
+    profile?: string;
+    scopeId?: string;
+    tenant?: string;
+}
+export interface RuntimeContext {
+    apiUrl: string;
+    authMethod: GrantConfig['authMethod'] | 'token';
+    config: GrantConfig;
+    profileName: string | null;
+    scope?: GrantScope;
+    originVerifySecret?: string;
+}
+/**
+ * Resolve API URL, credentials, and scope.
+ * Order: flags → GRANT_* env → named profile file.
+ */
+export declare function resolveRuntimeContext(flags?: RuntimeFlags): Promise<RuntimeContext>;

package/dist/config/index.d.ts

@@ -1,2 +1 @@
-export { resolveAccessToken } from './resolve-token.js';
 export { DEFAULT_PROFILE_NAME, getConfigPath, listProfileNames, loadConfigFile, loadProfile, saveConfigFile, } from './storage.js';

package/dist/config/output.d.ts

@@ -0,0 +1,3 @@
+export type OutputFormat = 'json' | 'text';
+export declare function parseOutputFormat(value: string | undefined): OutputFormat;
+export declare function printOutput(data: unknown, format: OutputFormat): void;

package/dist/config/resolve-token.d.ts

@@ -1,9 +1,8 @@
 import { GrantConfig } from '../types/config.js';
 /**
- * Resolve a valid access token from stored config.
- * Only tokens are stored (no credentials). Session auth does not auto-refresh; user must re-auth when the access token expires.
- *
- * - API key: exchanges clientId + clientSecret for a fresh token (no credentials stored after exchange).
- * - Session: returns the stored access token. When it expires, the user must run "grant start" again to re-authenticate.
+ * Resolve a valid access token from env or stored config.
+ * API key: exchanges clientId + clientSecret for a fresh token.
+ * Session: returns the stored access token. GRANT_ACCESS_TOKEN wins when set.
  */
 export declare function resolveAccessToken(config: GrantConfig): Promise<string>;
+export declare function refreshAndPersistSession(config: GrantConfig, profileName?: string | null): Promise<string>;