@parmana/sdk 1.1.0

package/dist/transport/HttpTransport.js

@@ -0,0 +1,193 @@
+/**
+ * Parmana SDK
+ *
+ * Canonical HTTP transport.
+ *
+ * Responsibilities:
+ * - Send HTTP requests.
+ * - Serialize request bodies.
+ * - Deserialize responses.
+ * - Return canonical TransportResponse objects.
+ *
+ * This transport does NOT:
+ * - evaluate policy
+ * - authorize execution
+ * - implement business logic
+ */
+import { RetryStrategy, } from "../config/RetryPolicy.js";
+import { ParmanaError, } from "../errors/ParmanaError.js";
+import { NetworkError, } from "../errors/NetworkError.js";
+import { TimeoutError, } from "../errors/TimeoutError.js";
+import { InternalServerError, } from "../errors/InternalServerError.js";
+import { RateLimitError, } from "../errors/RateLimitError.js";
+import { mapHttpErrorResponse, } from "./mapHttpErrorResponse.js";
+/**
+ * Retries are restricted to idempotent methods only. A retried POST
+ * (e.g. /execute) risks a second real side effect on the underlying
+ * system if the first attempt actually succeeded but the response was
+ * lost -- the server's own businessTransactionId uniqueness check turns
+ * that into a 409, not a duplicate execution, but blindly retrying
+ * non-idempotent requests is still not a safe default without deliberate
+ * per-route design this SDK doesn't have. Mirrors the Python SDK's own
+ * documented choice (urllib3 Retry scoped to GET only).
+ */
+const RETRYABLE_METHODS = ["GET"];
+/**
+ * Every 5xx this API can return for a GET request maps to
+ * InternalServerError (mapHttpErrorResponse.ts only special-cases 4xx
+ * statuses individually) -- so "retryable HTTP failure" is exactly
+ * "InternalServerError on a GET", no separate status-code bookkeeping
+ * needed. Network failures and timeouts are retryable regardless of
+ * which HTTP status (if any) was ever reached. RateLimitError (429) is
+ * retryable too -- GET /health,/ready are IP-rate-limited (see
+ * packages/api's rate-limiting middleware) and a caller polling them on
+ * a fixed interval should be able to just wait out the window rather
+ * than handling 429 specially. POST /execute is also rate-limited, but
+ * RETRYABLE_METHODS already excludes POST for the unrelated
+ * non-idempotency reason above, so this doesn't risk a double-submit.
+ * Note: retry timing here still follows the configured backoff
+ * (delayForAttempt below), not RateLimitError.retryAfterSeconds -- the
+ * Runtime's hint is exposed on the error for a caller that wants to
+ * honor it directly, but isn't yet wired into this loop's own delay.
+ */
+function isRetryableFailure(error) {
+    return (error instanceof NetworkError ||
+        error instanceof TimeoutError ||
+        error instanceof InternalServerError ||
+        error instanceof RateLimitError);
+}
+function delayForAttempt(attempt, policy) {
+    const raw = policy.strategy === RetryStrategy.FIXED
+        ? policy.initialDelayMs
+        : policy.initialDelayMs * 2 ** attempt;
+    return Math.min(raw, policy.maxDelayMs);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Resolves the effective retry policy for a request, or undefined when
+ * retries do not apply at all -- disabled, no configuration.retryPolicy,
+ * maxAttempts <= 0 (the documented default), or a non-idempotent method.
+ * Every field below mirrors RetryPolicy.ts's own documented defaults.
+ */
+function resolveRetryPolicy(configuration, method) {
+    const policy = configuration.retryPolicy;
+    if (policy?.enabled !== true) {
+        return undefined;
+    }
+    const maxAttempts = policy.maxAttempts ?? 0;
+    if (maxAttempts <= 0) {
+        return undefined;
+    }
+    if (!RETRYABLE_METHODS.includes(method)) {
+        return undefined;
+    }
+    return {
+        maxAttempts,
+        initialDelayMs: policy.initialDelayMs ?? 1000,
+        maxDelayMs: policy.maxDelayMs ?? 30_000,
+        strategy: policy.strategy ?? RetryStrategy.EXPONENTIAL,
+    };
+}
+export class HttpTransport {
+    configuration;
+    constructor(configuration) {
+        this.configuration = configuration;
+    }
+    async send(request) {
+        const retryPolicy = resolveRetryPolicy(this.configuration, request.method);
+        if (retryPolicy === undefined) {
+            return this.attempt(request);
+        }
+        // maxAttempts counts retries, not the initial try -- maxAttempts: 3
+        // means up to 4 total requests (1 initial + 3 retries), matching
+        // RetryPolicy.ts's own doc comment ("Maximum retry attempts").
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.attempt(request);
+            }
+            catch (error) {
+                const canRetry = isRetryableFailure(error) && attempt < retryPolicy.maxAttempts;
+                if (!canRetry) {
+                    throw error;
+                }
+                await sleep(delayForAttempt(attempt, retryPolicy));
+            }
+        }
+    }
+    async attempt(request) {
+        const controller = new AbortController();
+        const timeout = this.configuration.timeout ??
+            30_000;
+        const timer = setTimeout(() => controller.abort(), timeout);
+        try {
+            const init = {
+                method: request.method,
+                headers: {
+                    "Content-Type": "application/json",
+                    ...(this.configuration.apiKey !== undefined && {
+                        Authorization: `Bearer ${this.configuration.apiKey}`,
+                    }),
+                    ...(request.headers ?? {}),
+                },
+                signal: controller.signal,
+            };
+            if (request.body !== undefined) {
+                init.body =
+                    JSON.stringify(request.body);
+            }
+            const response = await fetch(this.configuration.endpoint +
+                request.path, init);
+            clearTimeout(timer);
+            const headers = {};
+            response.headers.forEach((value, key) => {
+                headers[key] = value;
+            });
+            let body;
+            if (response.status === 204) {
+                body = undefined;
+            }
+            else {
+                try {
+                    body =
+                        (await response.json());
+                }
+                catch {
+                    // A non-JSON or empty body. Real, error-envelope
+                    // responses from this API are always JSON; this only
+                    // guards mapHttpErrorResponse below against an
+                    // unparseable body rather than throwing an opaque
+                    // SyntaxError for it.
+                    body = undefined;
+                }
+            }
+            if (response.status >= 400 &&
+                !(request.nonThrowingStatuses ?? []).includes(response.status)) {
+                throw mapHttpErrorResponse(response.status, body, headers);
+            }
+            return {
+                status: response.status,
+                headers,
+                body,
+            };
+        }
+        catch (error) {
+            clearTimeout(timer);
+            if (error instanceof ParmanaError) {
+                // Already the correct typed error (mapHttpErrorResponse,
+                // above) — rethrow as-is, do not fold it into NetworkError.
+                throw error;
+            }
+            if (error instanceof DOMException &&
+                error.name ===
+                    "AbortError") {
+                throw new TimeoutError("Request timed out.");
+            }
+            throw new NetworkError("Unable to communicate with the Parmana Runtime.", {
+                cause: error,
+            });
+        }
+    }
+}
+//# sourceMappingURL=HttpTransport.js.map

package/dist/transport/HttpTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpTransport.js","sourceRoot":"","sources":["../../src/transport/HttpTransport.ts"],"names":[],"mappings":"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"}

package/dist/transport/mapHttpErrorResponse.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Parmana SDK
+ *
+ * Maps a non-2xx HTTP response from the Parmana Runtime to the
+ * corresponding typed SDK error.
+ *
+ * The real Runtime envelope (packages/api/src/middleware/error-handler.ts)
+ * is `{ "error": string }`, sometimes with a second `code` field. `code`
+ * is present only when the failure reached the shared error handler as a
+ * typed error carrying its own status/code (RuntimeError, or a
+ * ParmanaError subclass such as NonceAlreadyConsumedError); most 4xx
+ * responses carry no `code` at all. Classification below is therefore
+ * driven primarily by HTTP status, with `code` used to distinguish the
+ * cases that need it. This API returns THREE distinct 403 shapes, not
+ * two — a fact this docstring previously got wrong:
+ * - `code: "POLICY_DENIED"` — a policy REJECTED decision, mapped to
+ *   ExecutionRejectedError, checked first since it needs a wholly
+ *   different SDK error class.
+ * - `code: "CAPABILITY_NOT_ALLOWED"` — a caller invoking a capability
+ *   it isn't permitted to invoke (isCapabilityAllowed.ts). Checked
+ *   explicitly (not left to fall through the generic status branch
+ *   below) so its `code` is preserved on AuthorizationError.serverCode
+ *   instead of being silently dropped.
+ * - no `code` at all — a caller asserting an authority.principalId it
+ *   isn't permitted to assert (isPrincipalAllowed.ts,
+ *   packages/api/src/routes/execute.ts and transactions.ts). Also maps
+ *   to AuthorizationError, via the generic `status === 403` branch.
+ * See /api-reference/error-catalog for the exhaustive, real, verified
+ * list this mapping is built from.
+ *
+ * Previously, a policy rejection had no dedicated status of its own and
+ * fell through to a generic `500` with `code: "RUNTIME_ERROR"` — this
+ * function used to special-case exactly that shape to still produce an
+ * ExecutionRejectedError. That gap is now fixed at the source
+ * (packages/runtime/src/ExecutionGate.ts, packages/api/src/middleware/
+ * error-handler.ts); this mapping was updated to match, not to work
+ * around the old ambiguity.
+ *
+ * One route, POST /policies/validate, does not use this envelope at all
+ * (every status it returns is `{valid, errors}`); PolicyApi.validate
+ * opts out of this mapping entirely via TransportRequest.throwOnHttpError,
+ * so this function is never called for that route's responses.
+ */
+import type { ParmanaError } from "../errors/ParmanaError.js";
+/**
+ * Maps a non-2xx HTTP response to the typed SDK error it should be
+ * thrown as. `headers` is optional only so existing direct callers
+ * (tests, primarily) that don't have a header set need not supply one —
+ * every real HttpTransport response has one.
+ */
+export declare function mapHttpErrorResponse(status: number, body: unknown, headers?: Record<string, string>): ParmanaError;
+//# sourceMappingURL=mapHttpErrorResponse.d.ts.map

package/dist/transport/mapHttpErrorResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapHttpErrorResponse.d.ts","sourceRoot":"","sources":["../../src/transport/mapHttpErrorResponse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAUH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAyD9D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,YAAY,CAmDd"}

package/dist/transport/mapHttpErrorResponse.js

@@ -0,0 +1,134 @@
+/**
+ * Parmana SDK
+ *
+ * Maps a non-2xx HTTP response from the Parmana Runtime to the
+ * corresponding typed SDK error.
+ *
+ * The real Runtime envelope (packages/api/src/middleware/error-handler.ts)
+ * is `{ "error": string }`, sometimes with a second `code` field. `code`
+ * is present only when the failure reached the shared error handler as a
+ * typed error carrying its own status/code (RuntimeError, or a
+ * ParmanaError subclass such as NonceAlreadyConsumedError); most 4xx
+ * responses carry no `code` at all. Classification below is therefore
+ * driven primarily by HTTP status, with `code` used to distinguish the
+ * cases that need it. This API returns THREE distinct 403 shapes, not
+ * two — a fact this docstring previously got wrong:
+ * - `code: "POLICY_DENIED"` — a policy REJECTED decision, mapped to
+ *   ExecutionRejectedError, checked first since it needs a wholly
+ *   different SDK error class.
+ * - `code: "CAPABILITY_NOT_ALLOWED"` — a caller invoking a capability
+ *   it isn't permitted to invoke (isCapabilityAllowed.ts). Checked
+ *   explicitly (not left to fall through the generic status branch
+ *   below) so its `code` is preserved on AuthorizationError.serverCode
+ *   instead of being silently dropped.
+ * - no `code` at all — a caller asserting an authority.principalId it
+ *   isn't permitted to assert (isPrincipalAllowed.ts,
+ *   packages/api/src/routes/execute.ts and transactions.ts). Also maps
+ *   to AuthorizationError, via the generic `status === 403` branch.
+ * See /api-reference/error-catalog for the exhaustive, real, verified
+ * list this mapping is built from.
+ *
+ * Previously, a policy rejection had no dedicated status of its own and
+ * fell through to a generic `500` with `code: "RUNTIME_ERROR"` — this
+ * function used to special-case exactly that shape to still produce an
+ * ExecutionRejectedError. That gap is now fixed at the source
+ * (packages/runtime/src/ExecutionGate.ts, packages/api/src/middleware/
+ * error-handler.ts); this mapping was updated to match, not to work
+ * around the old ambiguity.
+ *
+ * One route, POST /policies/validate, does not use this envelope at all
+ * (every status it returns is `{valid, errors}`); PolicyApi.validate
+ * opts out of this mapping entirely via TransportRequest.throwOnHttpError,
+ * so this function is never called for that route's responses.
+ */
+import { ValidationError } from "../errors/ValidationError.js";
+import { AuthenticationError } from "../errors/AuthenticationError.js";
+import { AuthorizationError } from "../errors/AuthorizationError.js";
+import { NotFoundError } from "../errors/NotFoundError.js";
+import { ConflictError } from "../errors/ConflictError.js";
+import { ExecutionRejectedError } from "../errors/ExecutionRejectedError.js";
+import { RateLimitError } from "../errors/RateLimitError.js";
+import { InternalServerError } from "../errors/InternalServerError.js";
+function extractMessage(status, body) {
+    if (body !== null &&
+        typeof body === "object" &&
+        "error" in body) {
+        const message = body.error;
+        if (typeof message === "string" && message.length > 0) {
+            return message;
+        }
+    }
+    return `Request failed with status ${status}.`;
+}
+function extractCode(body) {
+    if (body !== null &&
+        typeof body === "object" &&
+        "code" in body) {
+        const code = body.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    return undefined;
+}
+/**
+ * Parses a `Retry-After` header value into seconds. Per RFC 9110 this is
+ * either an integer number of seconds or an HTTP-date; this API only
+ * ever sends the integer-seconds form (express-rate-limit's default),
+ * so an HTTP-date is treated as absent rather than guessed at.
+ */
+function extractRetryAfterSeconds(headers) {
+    const raw = headers?.["retry-after"];
+    if (raw === undefined) {
+        return undefined;
+    }
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}
+/**
+ * Maps a non-2xx HTTP response to the typed SDK error it should be
+ * thrown as. `headers` is optional only so existing direct callers
+ * (tests, primarily) that don't have a header set need not supply one —
+ * every real HttpTransport response has one.
+ */
+export function mapHttpErrorResponse(status, body, headers) {
+    const message = extractMessage(status, body);
+    const code = extractCode(body);
+    // Checked ahead of the generic status branches: a policy REJECTED
+    // decision carries this exact code alongside its 403 status, and must
+    // not be classified as the *other* 403 this API returns (a
+    // caller-identity/principal mismatch, which carries no code at all).
+    if (code === "POLICY_DENIED") {
+        return new ExecutionRejectedError(message);
+    }
+    // Also checked ahead of the generic status branches, for the same
+    // reason as POLICY_DENIED above: a capability-denied 403 carries this
+    // code, and letting it fall through to the generic `status === 403`
+    // branch below would still produce the right error class
+    // (AuthorizationError) but silently drop the code — checking it here
+    // preserves it on `serverCode` instead.
+    if (code === "CAPABILITY_NOT_ALLOWED") {
+        return new AuthorizationError(message, { serverCode: code });
+    }
+    if (status === 400) {
+        return new ValidationError(message);
+    }
+    if (status === 401) {
+        return new AuthenticationError(message);
+    }
+    if (status === 403) {
+        return new AuthorizationError(message);
+    }
+    if (status === 404) {
+        return new NotFoundError(message);
+    }
+    if (status === 409) {
+        return new ConflictError(message);
+    }
+    if (status === 429) {
+        const retryAfterSeconds = extractRetryAfterSeconds(headers);
+        return new RateLimitError(message, {
+            ...(retryAfterSeconds !== undefined && { retryAfterSeconds }),
+        });
+    }
+    return new InternalServerError(message);
+}
+//# sourceMappingURL=mapHttpErrorResponse.js.map

package/dist/transport/mapHttpErrorResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapHttpErrorResponse.js","sourceRoot":"","sources":["../../src/transport/mapHttpErrorResponse.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parmana TypeScript SDK
+ *
+ * SDK version.
+ */
+export declare const VERSION = "1.0.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,7 @@
+/**
+ * Parmana TypeScript SDK
+ *
+ * SDK version.
+ */
+export const VERSION = "1.0.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@parmana/sdk",
+  "version": "1.1.0",
+  "private": false,
+  "description": "Official Parmana TypeScript SDK",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rimraf dist"
+  },
+  "keywords": [
+    "parmana",
+    "ai",
+    "governance",
+    "authorization",
+    "verification",
+    "execution",
+    "trust",
+    "agentic-ai",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pavancharak/parmana-exp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pavancharak/parmana-exp/issues"
+  },
+  "homepage": "https://github.com/pavancharak/parmana-exp",
+  "dependencies": {
+    "dotenv": "^17.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}