@deepraxis/sdk 0.1.1-dev.cbec4d1 → 0.1.1-dev.cc84163

package/dist/core/credentials.d.ts

@@ -1,7 +1,9 @@
 /**
- * Default credential chain for code running on a Praxis computer (ticket-5367):
- * PRAXIS_API_TOKEN environment variable, then ~/.praxis/credentials. Resolved at call time so a
- * token the platform renewed in the file is picked up by an already-running process.
+ * Default credential chain for code running on a Praxis computer (ticket-5367, ADR-098 §2):
+ * the PRAXIS_API_TOKEN environment variable, then the login file of the environment,
+ * `~/.praxis/cli/<env>.json` — the one file `praxis login` writes for a person and the platform writes
+ * for a managed login. Resolved at call time so a token the platform renewed in the file is picked up
+ * by an already-running process.
  */
 export interface ResolvedCredentials {
     token?: string;
@@ -9,6 +11,13 @@ export interface ResolvedCredentials {
 }
 type Env = Record<string, string | undefined>;
 type ReadFile = (path: string) => string | null;
+/**
+ * Which environment's login file applies: PRAXIS_ENV when it names one, otherwise a `-develop.` host in
+ * PRAXIS_API_URL means develop and any other host production — the rule apps/cli/src/config/env.ts
+ * applies. A PRAXIS_ENV that is not a plain name is no environment at all and is ignored. Pure.
+ */
+export declare function credentialsEnv(env: Env): string;
+/** The one login file, the same path the CLI reads for this environment. Null without a home directory. Pure. */
 export declare function credentialsPath(env: Env): string | null;
 export declare function resolveDefaultCredentials(env?: Env, readFile?: ReadFile): ResolvedCredentials;
 export {};

package/dist/core/credentials.js

@@ -8,9 +8,29 @@ function defaultReadFile(path) {
         return null;
     }
 }
+/**
+ * Which environment's login file applies: PRAXIS_ENV when it names one, otherwise a `-develop.` host in
+ * PRAXIS_API_URL means develop and any other host production — the rule apps/cli/src/config/env.ts
+ * applies. A PRAXIS_ENV that is not a plain name is no environment at all and is ignored. Pure.
+ */
+export function credentialsEnv(env) {
+    const declared = nonEmpty(env.PRAXIS_ENV);
+    if (declared && /^[A-Za-z0-9_-]+$/.test(declared))
+        return declared;
+    const apiUrl = nonEmpty(env.PRAXIS_API_URL);
+    if (apiUrl) {
+        try {
+            if (new URL(apiUrl).hostname.includes('-develop.'))
+                return 'develop';
+        }
+        catch { /* a malformed URL is not evidence of develop */ }
+    }
+    return 'production';
+}
+/** The one login file, the same path the CLI reads for this environment. Null without a home directory. Pure. */
 export function credentialsPath(env) {
     const home = nonEmpty(env.HOME) ?? nonEmpty(env.USERPROFILE);
-    return home ? `${home.replace(/\/$/, '')}/.praxis/credentials` : null;
+    return home ? `${home.replace(/[/\\]+$/, '')}/.praxis/cli/${credentialsEnv(env)}.json` : null;
 }
 export function resolveDefaultCredentials(env = globalThis.process?.env ?? {}, readFile = defaultReadFile) {
     const envToken = nonEmpty(env.PRAXIS_API_TOKEN);
@@ -23,7 +43,7 @@ export function resolveDefaultCredentials(env = globalThis.process?.env ?? {}, r
         return envUrl ? { apiUrl: envUrl } : {};
     try {
         const file = JSON.parse(text);
-        const token = nonEmpty(file.token);
+        const token = nonEmpty(file.access_token);
         const apiUrl = envUrl ?? nonEmpty(file.api_url);
         return { ...(token ? { token } : {}), ...(apiUrl ? { apiUrl } : {}) };
     }

package/dist/core/errors.d.ts

@@ -9,6 +9,9 @@ export interface ProblemDetails {
     requestId?: string;
     message?: string;
     param?: string | null;
+    /** ticket-681 — the documentation page the failure points at, and the exact section to read. */
+    docUrl?: string;
+    describe?: string;
     raw?: unknown;
 }
 /** Pure normalization shared by HTTP clients and the automation call ledger.
@@ -26,6 +29,9 @@ export declare class PraxisError extends Error {
     readonly errors: unknown[];
     readonly requestId?: string;
     readonly param?: string | null;
+    /** ticket-681 — the documented page and the exact section an agent should read to fix the call. */
+    readonly docUrl?: string;
+    readonly describe?: string;
     readonly raw?: unknown;
     constructor(problem?: ProblemDetails, options?: ErrorOptions);
     static fromResponse(response: Response, body: unknown): PraxisError;

package/dist/core/errors.js

@@ -16,6 +16,9 @@ export function problemFrom(status, headers, body, statusText) {
         param: typeof param === 'string' ? param : param === null || nested.param === null ? null : undefined,
         errors: Array.isArray(value.errors) ? value.errors : [],
         requestId: headers.get('x-request-id') ?? string(value.requestId) ?? string(value.request_id),
+        // Both spellings reach here: the own face writes snake_case, an in-process problem keeps docUrl.
+        docUrl: string(nested.doc_url) ?? string(value.doc_url) ?? string(nested.docUrl) ?? string(value.docUrl),
+        describe: string(nested.describe) ?? string(value.describe),
         raw: body,
     };
 }
@@ -28,6 +31,9 @@ export class PraxisError extends Error {
     errors;
     requestId;
     param;
+    /** ticket-681 — the documented page and the exact section an agent should read to fix the call. */
+    docUrl;
+    describe;
     raw;
     constructor(problem = {}, options) {
         super(problem.message ?? problem.detail ?? problem.title ?? `Praxis request failed${problem.status ? ` (${problem.status})` : ''}`, options);
@@ -40,6 +46,8 @@ export class PraxisError extends Error {
         this.errors = problem.errors ?? [];
         this.requestId = problem.requestId;
         this.param = problem.param;
+        this.docUrl = problem.docUrl;
+        this.describe = problem.describe;
         this.raw = problem.raw;
     }
     static fromResponse(response, body) {

package/dist/core/transport.d.ts

@@ -1,6 +1,6 @@
 import { type SSEEvent } from './sse.js';
 export interface PraxisOptions {
-    /** Explicit key. Omitted on a Praxis computer: PRAXIS_API_TOKEN, then ~/.praxis/credentials, are used. */
+    /** Explicit key. Omitted on a Praxis computer: PRAXIS_API_TOKEN, then the login file `~/.praxis/cli/<env>.json`, are used. */
     apiKey?: string;
     baseUrl?: string;
     timeoutMs?: number;