@deepraxis/sdk 0.1.1-dev.ea4a5dd → 0.1.1-dev.eaacee7

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

@@ -25,6 +25,15 @@ type InternalOptions = RequestOptions & {
     query?: unknown;
     lastEventId?: string;
 };
+/** Margin over a server-side execution deadline: the response still has to travel back after it. */
+export declare const SERVER_DEADLINE_MARGIN_MS = 30000;
+/**
+ * A request body that carries its own execution deadline (`timeoutMs`, as in sandbox commands.run) is
+ * waited for at least that long plus a margin, so the client never gives up before the server answers.
+ */
+export declare function serverDeadlineMs(options: {
+    body?: unknown;
+}): number;
 export declare class Transport {
     private readonly config;
     constructor(options: PraxisOptions);

package/dist/core/transport.js

@@ -32,6 +32,17 @@ function assertKnownOptions(options) {
         detail: `Unrecognised option ${stray.length > 1 ? 'keys' : 'key'} ${names}. Request parameters are not flat: put each under \`query\` (GET/DELETE: filters, pagination), \`path\` (URL segments) or \`body\` (POST/PATCH/PUT payload), e.g. call({ query: { ${stray[0]} } }) or call({ body: { ${stray[0]} } }). Common top-level keys: path, query, body, headers, signal, timeoutMs, maxRetries.`,
     });
 }
+/** Margin over a server-side execution deadline: the response still has to travel back after it. */
+export const SERVER_DEADLINE_MARGIN_MS = 30_000;
+/**
+ * A request body that carries its own execution deadline (`timeoutMs`, as in sandbox commands.run) is
+ * waited for at least that long plus a margin, so the client never gives up before the server answers.
+ */
+export function serverDeadlineMs(options) {
+    const body = options.body;
+    const deadline = body && typeof body === 'object' ? body.timeoutMs : undefined;
+    return typeof deadline === 'number' && Number.isFinite(deadline) && deadline > 0 ? deadline + SERVER_DEADLINE_MARGIN_MS : 0;
+}
 export class Transport {
     config;
     constructor(options) {
@@ -46,7 +57,7 @@ export class Transport {
     }
     scope(options, streaming) {
         assertKnownOptions(options);
-        const timeoutMs = options.timeoutMs ?? this.config.timeoutMs;
+        const timeoutMs = options.timeoutMs ?? Math.max(this.config.timeoutMs, serverDeadlineMs(options));
         const maxRetries = options.maxRetries ?? this.config.maxRetries;
         this.validate(timeoutMs, maxRetries);
         const controller = new AbortController();