@getanyapi/sdk 0.9.6 → 0.9.8

package/dist/index.d.cts

@@ -8,8 +8,31 @@ interface RunResult<T> {
     provider: "AnyAPI";
     /** Amount charged in USD for this call. */
     costUsd: number;
-    /** Number of result rows returned (present on per-result SKUs). */
-    items?: number;
+    /**
+     * Number of result rows returned. Always present on the wire: the gateway's field
+     * carries no `omitempty`, and a metadata-only replay preserves the original count.
+     */
+    items: number;
+    /**
+     * True when the gateway served a stored response for a repeated Idempotency-Key instead
+     * of running the SKU again. A replay is not billed twice. Always present on the wire.
+     *
+     * A replay whose stored payload is no longer retained (a 24h TTL expiry, or a payload
+     * that exceeded the storage size cap) arrives with the metadata only and `output` null,
+     * which {@link unwrap} rejects. See SPEC 2.3.
+     */
+    replayed: boolean;
+    /**
+     * Opaque handle to the full unshaped result, cached for about 15 minutes, so it can be
+     * re-read and re-shaped for free via GET /v1/results/{id}. Absent when the gateway did
+     * not cache the result.
+     */
+    resultId?: string;
+    /**
+     * Why a requested jq reshape did not apply. The run was still billed and `output` carries
+     * the full unshaped result. Absent when no jq was requested or it succeeded.
+     */
+    jqError?: string;
     /** Optional server nudge when a large result was returned untrimmed. */
     hint?: string;
 }
@@ -35,8 +58,31 @@ interface BareRunResult<T> {
     provider: "AnyAPI";
     /** Amount charged in USD for this call. */
     costUsd: number;
-    /** Number of result rows returned (present on per-result SKUs). */
-    items?: number;
+    /**
+     * Number of result rows returned. Always present on the wire: the gateway's field
+     * carries no `omitempty`, and a metadata-only replay preserves the original count.
+     */
+    items: number;
+    /**
+     * True when the gateway served a stored response for a repeated Idempotency-Key instead
+     * of running the SKU again. A replay is not billed twice. Always present on the wire.
+     *
+     * A replay whose stored payload is no longer retained (a 24h TTL expiry, or a payload
+     * that exceeded the storage size cap) arrives with the metadata only and `output` null,
+     * which {@link unwrap} rejects. See SPEC 2.3.
+     */
+    replayed: boolean;
+    /**
+     * Opaque handle to the full unshaped result, cached for about 15 minutes, so it can be
+     * re-read and re-shaped for free via GET /v1/results/{id}. Absent when the gateway did
+     * not cache the result.
+     */
+    resultId?: string;
+    /**
+     * Why a requested jq reshape did not apply. The run was still billed and `output` carries
+     * the full unshaped result. Absent when no jq was requested or it succeeded.
+     */
+    jqError?: string;
     /** Optional server nudge when a large result was returned untrimmed. */
     hint?: string;
 }
@@ -45,7 +91,10 @@ interface BareRunResult<T> {
  * matching entity. Narrows Output<T> to T.
  *
  * Two overloads: a found-data RunResult may be empty (throws when found is false); a bare
- * result always carries its data (returns output directly, never throws).
+ * result always carries its data (returns output directly).
+ *
+ * Either shape throws AnyAPIError when `output` is null: an idempotent replay can outlive
+ * its stored payload, and the caller must not receive `null` typed as T. See SPEC 2.3.
  */
 declare function unwrap<T>(result: BareRunResult<T>): T;
 declare function unwrap<T>(result: RunResult<T>): T;
@@ -294,7 +343,10 @@ declare function paginate<Item, Page extends RunResult<unknown> | BareRunResult<
 declare class AnyAPIError extends Error {
     /** HTTP status code, or 0 for transport-level failures (connection/timeout). */
     readonly status: number;
-    /** The x-request-id response header when present, else undefined. */
+    /**
+     * The gateway's X-Anyapi-Request-Id response header when present (falling back to a
+     * proxy-set x-request-id), else undefined. Quote it to AnyAPI support.
+     */
     readonly requestId?: string;
     /** Stable gateway error code when the JSON body includes one, else undefined. */
     readonly code?: string;

package/dist/index.d.ts

@@ -8,8 +8,31 @@ interface RunResult<T> {
     provider: "AnyAPI";
     /** Amount charged in USD for this call. */
     costUsd: number;
-    /** Number of result rows returned (present on per-result SKUs). */
-    items?: number;
+    /**
+     * Number of result rows returned. Always present on the wire: the gateway's field
+     * carries no `omitempty`, and a metadata-only replay preserves the original count.
+     */
+    items: number;
+    /**
+     * True when the gateway served a stored response for a repeated Idempotency-Key instead
+     * of running the SKU again. A replay is not billed twice. Always present on the wire.
+     *
+     * A replay whose stored payload is no longer retained (a 24h TTL expiry, or a payload
+     * that exceeded the storage size cap) arrives with the metadata only and `output` null,
+     * which {@link unwrap} rejects. See SPEC 2.3.
+     */
+    replayed: boolean;
+    /**
+     * Opaque handle to the full unshaped result, cached for about 15 minutes, so it can be
+     * re-read and re-shaped for free via GET /v1/results/{id}. Absent when the gateway did
+     * not cache the result.
+     */
+    resultId?: string;
+    /**
+     * Why a requested jq reshape did not apply. The run was still billed and `output` carries
+     * the full unshaped result. Absent when no jq was requested or it succeeded.
+     */
+    jqError?: string;
     /** Optional server nudge when a large result was returned untrimmed. */
     hint?: string;
 }
@@ -35,8 +58,31 @@ interface BareRunResult<T> {
     provider: "AnyAPI";
     /** Amount charged in USD for this call. */
     costUsd: number;
-    /** Number of result rows returned (present on per-result SKUs). */
-    items?: number;
+    /**
+     * Number of result rows returned. Always present on the wire: the gateway's field
+     * carries no `omitempty`, and a metadata-only replay preserves the original count.
+     */
+    items: number;
+    /**
+     * True when the gateway served a stored response for a repeated Idempotency-Key instead
+     * of running the SKU again. A replay is not billed twice. Always present on the wire.
+     *
+     * A replay whose stored payload is no longer retained (a 24h TTL expiry, or a payload
+     * that exceeded the storage size cap) arrives with the metadata only and `output` null,
+     * which {@link unwrap} rejects. See SPEC 2.3.
+     */
+    replayed: boolean;
+    /**
+     * Opaque handle to the full unshaped result, cached for about 15 minutes, so it can be
+     * re-read and re-shaped for free via GET /v1/results/{id}. Absent when the gateway did
+     * not cache the result.
+     */
+    resultId?: string;
+    /**
+     * Why a requested jq reshape did not apply. The run was still billed and `output` carries
+     * the full unshaped result. Absent when no jq was requested or it succeeded.
+     */
+    jqError?: string;
     /** Optional server nudge when a large result was returned untrimmed. */
     hint?: string;
 }
@@ -45,7 +91,10 @@ interface BareRunResult<T> {
  * matching entity. Narrows Output<T> to T.
  *
  * Two overloads: a found-data RunResult may be empty (throws when found is false); a bare
- * result always carries its data (returns output directly, never throws).
+ * result always carries its data (returns output directly).
+ *
+ * Either shape throws AnyAPIError when `output` is null: an idempotent replay can outlive
+ * its stored payload, and the caller must not receive `null` typed as T. See SPEC 2.3.
  */
 declare function unwrap<T>(result: BareRunResult<T>): T;
 declare function unwrap<T>(result: RunResult<T>): T;
@@ -294,7 +343,10 @@ declare function paginate<Item, Page extends RunResult<unknown> | BareRunResult<
 declare class AnyAPIError extends Error {
     /** HTTP status code, or 0 for transport-level failures (connection/timeout). */
     readonly status: number;
-    /** The x-request-id response header when present, else undefined. */
+    /**
+     * The gateway's X-Anyapi-Request-Id response header when present (falling back to a
+     * proxy-set x-request-id), else undefined. Quote it to AnyAPI support.
+     */
     readonly requestId?: string;
     /** Stable gateway error code when the JSON body includes one, else undefined. */
     readonly code?: string;

package/dist/index.js

@@ -2,7 +2,10 @@
 var AnyAPIError = class extends Error {
   /** HTTP status code, or 0 for transport-level failures (connection/timeout). */
   status;
-  /** The x-request-id response header when present, else undefined. */
+  /**
+   * The gateway's X-Anyapi-Request-Id response header when present (falling back to a
+   * proxy-set x-request-id), else undefined. Quote it to AnyAPI support.
+   */
   requestId;
   /** Stable gateway error code when the JSON body includes one, else undefined. */
   code;
@@ -37,6 +40,14 @@ var ConnectionError = class extends AnyAPIError {
 };
 var TimeoutError = class extends AnyAPIError {
 };
+var REQUEST_ID_HEADERS = ["x-anyapi-request-id", "x-request-id"];
+function requestIdOf(headers) {
+  for (const name of REQUEST_ID_HEADERS) {
+    const value = headers.get(name);
+    if (value) return value;
+  }
+  return void 0;
+}
 function errorFromStatus(status, message, requestId, code) {
   switch (status) {
     case 400:
@@ -407,7 +418,7 @@ async function agentSignup(options = {}) {
       0
     );
   }
-  const requestId = response.headers.get("x-request-id") ?? void 0;
+  const requestId = requestIdOf(response.headers);
   const text = await response.text().catch(() => "");
   if (response.status !== 200) {
     let message = `request failed with status ${response.status}`;
@@ -750,7 +761,7 @@ var AnyAPI = class {
         }
         throw connErr;
       }
-      const requestId = response.headers.get("x-request-id") ?? void 0;
+      const requestId = requestIdOf(response.headers);
       if (response.status === 200) {
         const text = await response.text();
         try {
@@ -788,8 +799,12 @@ var AnyAPI = class {
 };
 
 // src/core/types.ts
+var OUTPUT_NOT_RETAINED = "the run output was not retained: this response is an idempotent replay whose stored payload has expired or was too large to store, so only the run metadata came back. Re-run the request without the idempotency key (or with a fresh one) to fetch the data again.";
 function unwrap(result) {
   const output = result.output;
+  if (output === null || output === void 0) {
+    throw new AnyAPIError(OUTPUT_NOT_RETAINED, 200);
+  }
   if (output !== null && typeof output === "object" && "found" in output) {
     const env = output;
     if (env.found) {