@prampta/sdk 0.7.0 → 0.8.0

package/README.md

@@ -95,6 +95,39 @@ const decision = await pg.assertLicensed(subjectCode, {
 // Apply the decision's obligations, generate, then submit a receipt.
 ```
 
+## The whole cycle in one call (0.8.0)
+
+`generateAuthorized` does what every integration otherwise writes by hand:
+
+- asks fresh for **every subject in the output** (a person, a voice, a brand…)
+  and generates only if **all** of them return a licence-backed `allow`;
+- never reuses a stored allow, and checks each is still live right before it
+  starts, so a pause or revocation stops the next generation;
+- files one receipt per subject;
+- gives the allows back (`releaseDecision`) when a subject refuses or your
+  `generate` throws, so a failed job does not use up a licence limit;
+- with a `journal` (your own database), never generates twice after a crash:
+  a repeat call resends missing receipts, or refuses a job that crashed
+  midway instead of rerunning it.
+
+```typescript
+const result = await pg.generateAuthorized(
+  { subjectIds: [personCode, voiceCode], generationId: jobId, promptHash,
+    modality: "video", model: modelName,
+    intendedUse: { useCase: "commercial", rights: ["output_generation"] } },
+  async (decisions) => {
+    // Apply every decision's obligations here. Throw only if nothing was produced.
+    const video = await render(prompt);
+    return { output: video, outputBytes: video.bytes };
+  },
+  { journal: { get: (id) => db.jobs.get(id), put: (e) => db.jobs.put(e) } },
+);
+if (result.unreported.length) retryLater(jobId); // receipts are resent by calling again
+```
+
+It uses `assertLicensed` (pinned operator keys required). The journal needs
+`put` to resolve only after a durable write.
+
 ## Check answers against PRE-GEN (recommended)
 
 ```typescript

package/dist/index.d.mts

@@ -381,6 +381,36 @@ interface LicenseRequestResult {
     requestId: string;
     status: string;
 }
+/** One generation as `generateAuthorized` records it. Stored by the
+ * provider, in its own database, so a crash never leads to generating twice. */
+interface GenerationJournalEntry {
+    generationId: string;
+    /** authorized: allows held, generation may have started.
+     * generated: output exists, receipts may be missing.
+     * reported: receipts filed. released: nothing produced, allows given back. */
+    stage: "authorized" | "generated" | "reported" | "released";
+    decisions: SignedDecision[];
+    outputHash?: string;
+}
+interface GenerationJournal {
+    get(generationId: string): Promise<GenerationJournalEntry | null>;
+    /** Resolve only after a durable write. */
+    put(entry: GenerationJournalEntry): Promise<void>;
+}
+type ReceiptOptions = Omit<NonNullable<Parameters<Prampta["submitReceipt"]>[1]>, "outputHash">;
+interface AuthorizedGeneration<T> {
+    /** generated: ran now. recovered: output existed from an earlier run, only
+     * receipts were sent. already_reported: nothing left to do. */
+    status: "generated" | "recovered" | "already_reported";
+    /** Only for status "generated"; after a recovery the output is wherever
+     * your earlier run stored it. */
+    output?: T;
+    decisions: SignedDecision[];
+    outputHash: string;
+    /** Receipts that could not be filed yet. Call again with the same
+     * generationId (needs a journal) or submitReceipt() for each. */
+    unreported: SignedDecision[];
+}
 interface OutputMetadata {
     prampta_decision_id: string;
     prampta_license_id: string | null;
@@ -484,6 +514,7 @@ declare class Prampta {
     private keySetCache;
     private keySetPromise;
     private tofuWarned;
+    private readonly inFlight;
     constructor(config?: PramptaConfig);
     /** V-11: a PG code is answered only by the registry that owns its namespace. */
     private assertPregenEndpoint;
@@ -559,6 +590,41 @@ declare class Prampta {
         decision: SignedDecision;
         metadata: OutputMetadata;
     }>;
+    /**
+     * The whole cycle in one call, for every subject in the output:
+     * ask PRAMPTA fresh for each subject (no cached allow is reused), require a
+     * licence-backed allow from all of them, generate, file one receipt per
+     * subject. If any subject refuses, or `generate` throws, the allows already
+     * held are released so they do not count against usage limits.
+     *
+     * `generate` must throw only when nothing was produced. With a `journal`,
+     * calling again with the same generationId after a crash never generates
+     * twice: it resends missing receipts, or refuses if the crash happened
+     * mid-generation (then check your own records, releaseDecision() if nothing
+     * was produced, and use a new generationId). Concurrent calls with the
+     * same generationId in this process share one run.
+     */
+    generateAuthorized<T>(request: Omit<VerifyRequest, "subjectId" | "generationId"> & {
+        subjectIds: string[];
+        generationId: string;
+    }, generate: (decisions: SignedDecision[]) => Promise<{
+        output: T;
+        outputHash?: string;
+        outputBytes?: Uint8Array | string;
+    }>, options?: {
+        journal?: GenerationJournal;
+        receipt?: ReceiptOptions;
+    }): Promise<AuthorizedGeneration<T>>;
+    private runAuthorized;
+    /** Returns the decisions whose receipt could not be filed. A receipt that
+     * already exists (an earlier attempt landed) counts as filed. */
+    private fileReceipts;
+    /** True when every allow was given back. */
+    private releaseAll;
+    /** Give back an allow that produced nothing (failed or cancelled job), so
+     * it does not count against the licence's usage limit. Only before a
+     * receipt and within 24 hours; the release is recorded in the audit log. */
+    releaseDecision(decisionId: string, reason?: string): Promise<Record<string, unknown>>;
     getSubject(subjectId: string): Promise<SubjectInfo | null>;
     requestLicense(input: LicenseRequestInput): Promise<LicenseRequestResult>;
     createOutputMetadata(decision: SignedDecision): OutputMetadata;
@@ -612,4 +678,4 @@ declare class Prampta {
     private getOnce;
 }
 
-export { type DeliveryResult, HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type LicenseSignatureInput, type Observation, type ObservationOutbox, type OutputMetadata, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaNetworkError, PramptaRefusalError, PramptaReporter, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, REFUSAL_DESCRIPTIONS, RegistryDirectoryError, type RegistryDirectoryOptions, type ReportInput, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, TrustedRegistryDirectory, type VerifyOptions, type VerifyRequest, canonicalJson, hashPrompt, matchSubjects, normalizeForMatch, verifyLicenseSignatures, verifyMerkleProof };
+export { type AuthorizedGeneration, type DeliveryResult, type GenerationJournal, type GenerationJournalEntry, HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type LicenseSignatureInput, type Observation, type ObservationOutbox, type OutputMetadata, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaNetworkError, PramptaRefusalError, PramptaReporter, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, REFUSAL_DESCRIPTIONS, type ReceiptOptions, RegistryDirectoryError, type RegistryDirectoryOptions, type ReportInput, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, TrustedRegistryDirectory, type VerifyOptions, type VerifyRequest, canonicalJson, hashPrompt, matchSubjects, normalizeForMatch, verifyLicenseSignatures, verifyMerkleProof };

package/dist/index.d.ts

@@ -381,6 +381,36 @@ interface LicenseRequestResult {
     requestId: string;
     status: string;
 }
+/** One generation as `generateAuthorized` records it. Stored by the
+ * provider, in its own database, so a crash never leads to generating twice. */
+interface GenerationJournalEntry {
+    generationId: string;
+    /** authorized: allows held, generation may have started.
+     * generated: output exists, receipts may be missing.
+     * reported: receipts filed. released: nothing produced, allows given back. */
+    stage: "authorized" | "generated" | "reported" | "released";
+    decisions: SignedDecision[];
+    outputHash?: string;
+}
+interface GenerationJournal {
+    get(generationId: string): Promise<GenerationJournalEntry | null>;
+    /** Resolve only after a durable write. */
+    put(entry: GenerationJournalEntry): Promise<void>;
+}
+type ReceiptOptions = Omit<NonNullable<Parameters<Prampta["submitReceipt"]>[1]>, "outputHash">;
+interface AuthorizedGeneration<T> {
+    /** generated: ran now. recovered: output existed from an earlier run, only
+     * receipts were sent. already_reported: nothing left to do. */
+    status: "generated" | "recovered" | "already_reported";
+    /** Only for status "generated"; after a recovery the output is wherever
+     * your earlier run stored it. */
+    output?: T;
+    decisions: SignedDecision[];
+    outputHash: string;
+    /** Receipts that could not be filed yet. Call again with the same
+     * generationId (needs a journal) or submitReceipt() for each. */
+    unreported: SignedDecision[];
+}
 interface OutputMetadata {
     prampta_decision_id: string;
     prampta_license_id: string | null;
@@ -484,6 +514,7 @@ declare class Prampta {
     private keySetCache;
     private keySetPromise;
     private tofuWarned;
+    private readonly inFlight;
     constructor(config?: PramptaConfig);
     /** V-11: a PG code is answered only by the registry that owns its namespace. */
     private assertPregenEndpoint;
@@ -559,6 +590,41 @@ declare class Prampta {
         decision: SignedDecision;
         metadata: OutputMetadata;
     }>;
+    /**
+     * The whole cycle in one call, for every subject in the output:
+     * ask PRAMPTA fresh for each subject (no cached allow is reused), require a
+     * licence-backed allow from all of them, generate, file one receipt per
+     * subject. If any subject refuses, or `generate` throws, the allows already
+     * held are released so they do not count against usage limits.
+     *
+     * `generate` must throw only when nothing was produced. With a `journal`,
+     * calling again with the same generationId after a crash never generates
+     * twice: it resends missing receipts, or refuses if the crash happened
+     * mid-generation (then check your own records, releaseDecision() if nothing
+     * was produced, and use a new generationId). Concurrent calls with the
+     * same generationId in this process share one run.
+     */
+    generateAuthorized<T>(request: Omit<VerifyRequest, "subjectId" | "generationId"> & {
+        subjectIds: string[];
+        generationId: string;
+    }, generate: (decisions: SignedDecision[]) => Promise<{
+        output: T;
+        outputHash?: string;
+        outputBytes?: Uint8Array | string;
+    }>, options?: {
+        journal?: GenerationJournal;
+        receipt?: ReceiptOptions;
+    }): Promise<AuthorizedGeneration<T>>;
+    private runAuthorized;
+    /** Returns the decisions whose receipt could not be filed. A receipt that
+     * already exists (an earlier attempt landed) counts as filed. */
+    private fileReceipts;
+    /** True when every allow was given back. */
+    private releaseAll;
+    /** Give back an allow that produced nothing (failed or cancelled job), so
+     * it does not count against the licence's usage limit. Only before a
+     * receipt and within 24 hours; the release is recorded in the audit log. */
+    releaseDecision(decisionId: string, reason?: string): Promise<Record<string, unknown>>;
     getSubject(subjectId: string): Promise<SubjectInfo | null>;
     requestLicense(input: LicenseRequestInput): Promise<LicenseRequestResult>;
     createOutputMetadata(decision: SignedDecision): OutputMetadata;
@@ -612,4 +678,4 @@ declare class Prampta {
     private getOnce;
 }
 
-export { type DeliveryResult, HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type LicenseSignatureInput, type Observation, type ObservationOutbox, type OutputMetadata, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaNetworkError, PramptaRefusalError, PramptaReporter, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, REFUSAL_DESCRIPTIONS, RegistryDirectoryError, type RegistryDirectoryOptions, type ReportInput, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, TrustedRegistryDirectory, type VerifyOptions, type VerifyRequest, canonicalJson, hashPrompt, matchSubjects, normalizeForMatch, verifyLicenseSignatures, verifyMerkleProof };
+export { type AuthorizedGeneration, type DeliveryResult, type GenerationJournal, type GenerationJournalEntry, HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type LicenseSignatureInput, type Observation, type ObservationOutbox, type OutputMetadata, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaNetworkError, PramptaRefusalError, PramptaReporter, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, REFUSAL_DESCRIPTIONS, type ReceiptOptions, RegistryDirectoryError, type RegistryDirectoryOptions, type ReportInput, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, TrustedRegistryDirectory, type VerifyOptions, type VerifyRequest, canonicalJson, hashPrompt, matchSubjects, normalizeForMatch, verifyLicenseSignatures, verifyMerkleProof };

package/dist/index.js

@@ -602,6 +602,7 @@ var Prampta = class _Prampta {
   keySetCache = null;
   keySetPromise = null;
   tofuWarned = false;
+  inFlight = /* @__PURE__ */ new Map();
   constructor(config = {}) {
     this.baseUrl = (config.baseUrl || envVar("PRAMPTA_BASE_URL")).replace(/\/+$/, "");
     this.providerId = config.providerId || envVar("PRAMPTA_PROVIDER_ID");
@@ -1035,6 +1036,94 @@ var Prampta = class _Prampta {
     const metadata = this.createOutputMetadata(decision);
     return { output, decision, metadata };
   }
+  /**
+   * The whole cycle in one call, for every subject in the output:
+   * ask PRAMPTA fresh for each subject (no cached allow is reused), require a
+   * licence-backed allow from all of them, generate, file one receipt per
+   * subject. If any subject refuses, or `generate` throws, the allows already
+   * held are released so they do not count against usage limits.
+   *
+   * `generate` must throw only when nothing was produced. With a `journal`,
+   * calling again with the same generationId after a crash never generates
+   * twice: it resends missing receipts, or refuses if the crash happened
+   * mid-generation (then check your own records, releaseDecision() if nothing
+   * was produced, and use a new generationId). Concurrent calls with the
+   * same generationId in this process share one run.
+   */
+  async generateAuthorized(request, generate, options = {}) {
+    const id = request.generationId;
+    if (!id) throw new PramptaSchemaError("generateAuthorized requires a generationId");
+    const running = this.inFlight.get(id);
+    if (running) return running;
+    const run = this.runAuthorized(request, generate, options).finally(() => this.inFlight.delete(id));
+    this.inFlight.set(id, run);
+    return run;
+  }
+  async runAuthorized(request, generate, { journal, receipt }) {
+    const { subjectIds, generationId, ...rest } = request;
+    const subjects = [...new Set(subjectIds)];
+    if (subjects.length === 0) throw new PramptaSchemaError("generateAuthorized requires at least one subjectId");
+    const saved = await journal?.get(generationId);
+    if (saved?.stage === "authorized") {
+      throw new PramptaError(`Generation ${generationId} was interrupted after it was authorized; it is not run again. If nothing was produced, releaseDecision() each decision and use a new generationId.`);
+    }
+    if (saved?.stage === "reported") {
+      return { status: "already_reported", decisions: saved.decisions, outputHash: saved.outputHash ?? "", unreported: [] };
+    }
+    if (saved?.stage === "generated") {
+      const unreported2 = await this.fileReceipts(saved.decisions, saved.outputHash ?? "", receipt);
+      if (unreported2.length === 0) await journal.put({ ...saved, stage: "reported" });
+      return { status: "recovered", decisions: saved.decisions, outputHash: saved.outputHash ?? "", unreported: unreported2 };
+    }
+    const settled = await Promise.allSettled(subjects.map((s) => this.assertLicensed(s, { ...rest, generationId })));
+    const decisions = settled.flatMap((r) => r.status === "fulfilled" ? [r.value] : []);
+    const failed = settled.find((r) => r.status === "rejected");
+    if (failed) {
+      await this.releaseAll(decisions, "another subject in the same output was refused");
+      throw failed.reason;
+    }
+    if (decisions.some((d) => d.expiresAt <= Math.floor(Date.now() / 1e3))) {
+      await this.releaseAll(decisions, "expired before generation started");
+      throw new PramptaError("An authorization expired before generation started; ask again");
+    }
+    await journal?.put({ generationId, stage: "authorized", decisions });
+    let result;
+    try {
+      result = await generate(decisions);
+    } catch (e) {
+      if (await this.releaseAll(decisions, "generation failed")) {
+        await journal?.put({ generationId, stage: "released", decisions });
+      }
+      throw e;
+    }
+    const bytes = typeof result.outputBytes === "string" ? new TextEncoder().encode(result.outputBytes) : result.outputBytes;
+    const outputHash = result.outputHash ?? (bytes ? await sha256Bytes(bytes) : "");
+    await journal?.put({ generationId, stage: "generated", decisions, outputHash });
+    const unreported = await this.fileReceipts(decisions, outputHash, receipt);
+    if (unreported.length === 0) await journal?.put({ generationId, stage: "reported", decisions, outputHash });
+    return { status: "generated", output: result.output, decisions, outputHash, unreported };
+  }
+  /** Returns the decisions whose receipt could not be filed. A receipt that
+   * already exists (an earlier attempt landed) counts as filed. */
+  async fileReceipts(decisions, outputHash, receipt) {
+    const results = await Promise.allSettled(decisions.map((d) => this.submitReceipt(d, { ...receipt, outputHash })));
+    return decisions.filter((_, i) => {
+      const r = results[i];
+      if (r.status === "fulfilled") return false;
+      return !(r.reason instanceof PramptaApiError && r.reason.status === 409 && /already exists/.test(r.reason.detail));
+    });
+  }
+  /** True when every allow was given back. */
+  async releaseAll(decisions, reason) {
+    const results = await Promise.allSettled(decisions.map((d) => this.releaseDecision(d.decisionId, reason)));
+    return results.every((r) => r.status === "fulfilled" || r.reason instanceof PramptaApiError && r.reason.status === 409 && /nothing_to_release/.test(r.reason.detail));
+  }
+  /** Give back an allow that produced nothing (failed or cancelled job), so
+   * it does not count against the licence's usage limit. Only before a
+   * receipt and within 24 hours; the release is recorded in the audit log. */
+  async releaseDecision(decisionId, reason = "") {
+    return this.post(`/v1/receipts/${encodeURIComponent(decisionId)}/release`, { reason });
+  }
   // ── Subject Resolution ───────────────────────────────────────────────
   async getSubject(subjectId) {
     this.registryDirectory?.assertEndpoint(subjectId, this.baseUrl);
@@ -1263,7 +1352,7 @@ var Prampta = class _Prampta {
         detail = JSON.parse(text).detail ?? text;
       } catch {
       }
-      throw new PramptaApiError(resp.status, String(detail));
+      throw new PramptaApiError(resp.status, typeof detail === "string" ? detail : JSON.stringify(detail));
     }
     return resp.json();
   }

package/dist/index.mjs

@@ -547,6 +547,7 @@ var Prampta = class _Prampta {
   keySetCache = null;
   keySetPromise = null;
   tofuWarned = false;
+  inFlight = /* @__PURE__ */ new Map();
   constructor(config = {}) {
     this.baseUrl = (config.baseUrl || envVar("PRAMPTA_BASE_URL")).replace(/\/+$/, "");
     this.providerId = config.providerId || envVar("PRAMPTA_PROVIDER_ID");
@@ -980,6 +981,94 @@ var Prampta = class _Prampta {
     const metadata = this.createOutputMetadata(decision);
     return { output, decision, metadata };
   }
+  /**
+   * The whole cycle in one call, for every subject in the output:
+   * ask PRAMPTA fresh for each subject (no cached allow is reused), require a
+   * licence-backed allow from all of them, generate, file one receipt per
+   * subject. If any subject refuses, or `generate` throws, the allows already
+   * held are released so they do not count against usage limits.
+   *
+   * `generate` must throw only when nothing was produced. With a `journal`,
+   * calling again with the same generationId after a crash never generates
+   * twice: it resends missing receipts, or refuses if the crash happened
+   * mid-generation (then check your own records, releaseDecision() if nothing
+   * was produced, and use a new generationId). Concurrent calls with the
+   * same generationId in this process share one run.
+   */
+  async generateAuthorized(request, generate, options = {}) {
+    const id = request.generationId;
+    if (!id) throw new PramptaSchemaError("generateAuthorized requires a generationId");
+    const running = this.inFlight.get(id);
+    if (running) return running;
+    const run = this.runAuthorized(request, generate, options).finally(() => this.inFlight.delete(id));
+    this.inFlight.set(id, run);
+    return run;
+  }
+  async runAuthorized(request, generate, { journal, receipt }) {
+    const { subjectIds, generationId, ...rest } = request;
+    const subjects = [...new Set(subjectIds)];
+    if (subjects.length === 0) throw new PramptaSchemaError("generateAuthorized requires at least one subjectId");
+    const saved = await journal?.get(generationId);
+    if (saved?.stage === "authorized") {
+      throw new PramptaError(`Generation ${generationId} was interrupted after it was authorized; it is not run again. If nothing was produced, releaseDecision() each decision and use a new generationId.`);
+    }
+    if (saved?.stage === "reported") {
+      return { status: "already_reported", decisions: saved.decisions, outputHash: saved.outputHash ?? "", unreported: [] };
+    }
+    if (saved?.stage === "generated") {
+      const unreported2 = await this.fileReceipts(saved.decisions, saved.outputHash ?? "", receipt);
+      if (unreported2.length === 0) await journal.put({ ...saved, stage: "reported" });
+      return { status: "recovered", decisions: saved.decisions, outputHash: saved.outputHash ?? "", unreported: unreported2 };
+    }
+    const settled = await Promise.allSettled(subjects.map((s) => this.assertLicensed(s, { ...rest, generationId })));
+    const decisions = settled.flatMap((r) => r.status === "fulfilled" ? [r.value] : []);
+    const failed = settled.find((r) => r.status === "rejected");
+    if (failed) {
+      await this.releaseAll(decisions, "another subject in the same output was refused");
+      throw failed.reason;
+    }
+    if (decisions.some((d) => d.expiresAt <= Math.floor(Date.now() / 1e3))) {
+      await this.releaseAll(decisions, "expired before generation started");
+      throw new PramptaError("An authorization expired before generation started; ask again");
+    }
+    await journal?.put({ generationId, stage: "authorized", decisions });
+    let result;
+    try {
+      result = await generate(decisions);
+    } catch (e) {
+      if (await this.releaseAll(decisions, "generation failed")) {
+        await journal?.put({ generationId, stage: "released", decisions });
+      }
+      throw e;
+    }
+    const bytes = typeof result.outputBytes === "string" ? new TextEncoder().encode(result.outputBytes) : result.outputBytes;
+    const outputHash = result.outputHash ?? (bytes ? await sha256Bytes(bytes) : "");
+    await journal?.put({ generationId, stage: "generated", decisions, outputHash });
+    const unreported = await this.fileReceipts(decisions, outputHash, receipt);
+    if (unreported.length === 0) await journal?.put({ generationId, stage: "reported", decisions, outputHash });
+    return { status: "generated", output: result.output, decisions, outputHash, unreported };
+  }
+  /** Returns the decisions whose receipt could not be filed. A receipt that
+   * already exists (an earlier attempt landed) counts as filed. */
+  async fileReceipts(decisions, outputHash, receipt) {
+    const results = await Promise.allSettled(decisions.map((d) => this.submitReceipt(d, { ...receipt, outputHash })));
+    return decisions.filter((_, i) => {
+      const r = results[i];
+      if (r.status === "fulfilled") return false;
+      return !(r.reason instanceof PramptaApiError && r.reason.status === 409 && /already exists/.test(r.reason.detail));
+    });
+  }
+  /** True when every allow was given back. */
+  async releaseAll(decisions, reason) {
+    const results = await Promise.allSettled(decisions.map((d) => this.releaseDecision(d.decisionId, reason)));
+    return results.every((r) => r.status === "fulfilled" || r.reason instanceof PramptaApiError && r.reason.status === 409 && /nothing_to_release/.test(r.reason.detail));
+  }
+  /** Give back an allow that produced nothing (failed or cancelled job), so
+   * it does not count against the licence's usage limit. Only before a
+   * receipt and within 24 hours; the release is recorded in the audit log. */
+  async releaseDecision(decisionId, reason = "") {
+    return this.post(`/v1/receipts/${encodeURIComponent(decisionId)}/release`, { reason });
+  }
   // ── Subject Resolution ───────────────────────────────────────────────
   async getSubject(subjectId) {
     this.registryDirectory?.assertEndpoint(subjectId, this.baseUrl);
@@ -1208,7 +1297,7 @@ var Prampta = class _Prampta {
         detail = JSON.parse(text).detail ?? text;
       } catch {
       }
-      throw new PramptaApiError(resp.status, String(detail));
+      throw new PramptaApiError(resp.status, typeof detail === "string" ? detail : JSON.stringify(detail));
     }
     return resp.json();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prampta/sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "PRAMPTA SDK — authorization before generation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",