@puku-ai/sdk 4.0.1 → 4.0.2

package/dist/vendor/lib/helper-client.js

@@ -0,0 +1,55 @@
+import { PukuError } from '../core/error.js';
+import { buildHeaders } from '../internal/headers.js';
+import { STAINLESS_HELPER_HEADER, } from '../internal/stainless-helper-header.js';
+/**
+ * Return a `withOptions()` clone of `client` set up for use *by* one of the
+ * runner helpers: authenticated with `authToken` as Bearer credentials, with
+ * the parent's `X-Api-Key` cleared, and tagged with the helper's
+ * `x-stainless-helper` value on every outgoing request.
+ *
+ * The returned sub-client inherits the parent's full configuration
+ * (`baseURL`, `timeout`, `maxRetries`, `fetch`, `fetchOptions`, custom
+ * `defaultHeaders`, `defaultQuery`). Overrides applied:
+ *
+ * - `authToken: authToken` — the new credential.
+ * - `apiKey: null` — the parent's `X-Api-Key` is cleared. `withOptions`
+ *   inherits the parent's `apiKey` by default; without this, both
+ *   `X-Api-Key` *and* `Authorization: Bearer …` would land on the wire.
+ *   `client.ts` only triggers the env-var fallback when `apiKey === undefined`,
+ *   so explicit `null` is honored.
+ * - `credentials: undefined` — opts the clone out of any inherited
+ *   credentials/config/profile so the explicit bearer is the unambiguous auth.
+ * - `baseURL: client.baseURL` — pins the parent's resolved host (auth override otherwise resets it).
+ * - `defaultHeaders` is rebuilt as `parent._authState.extraHeaders ⊕ parent.defaultHeaders ⊕
+ *   {'x-stainless-helper': helper}`. `withOptions` *replaces* (does not
+ *   merge) `defaultHeaders`, so we merge here so any custom headers the
+ *   caller set on the parent client survive on the sub-client.
+ */
+export function copyClientForHelper(client, { authToken, helper }) {
+    if (!authToken) {
+        throw new PukuError(`copyClientForHelper: expected a non-empty authToken but received ${JSON.stringify(authToken)}`);
+    }
+    const internal = client;
+    const parentDefaults = internal._options.defaultHeaders;
+    // Carry the parent's credential/profile headers; strip the auth ones (we re-auth below).
+    const parentAuthExtraHeaders = internal._authState?.extraHeaders;
+    const inheritedAuthExtraHeaders = parentAuthExtraHeaders ?
+        Object.fromEntries(Object.entries(parentAuthExtraHeaders).filter(([name]) => {
+            const lower = name.toLowerCase();
+            return lower !== 'authorization' && lower !== 'x-api-key';
+        }))
+        : undefined;
+    const defaultHeaders = buildHeaders([
+        inheritedAuthExtraHeaders,
+        parentDefaults,
+        { [STAINLESS_HELPER_HEADER]: helper },
+    ]);
+    return client.withOptions({
+        apiKey: null,
+        authToken,
+        baseURL: client.baseURL,
+        credentials: undefined,
+        defaultHeaders,
+    });
+}
+//# sourceMappingURL=helper-client.js.map

package/dist/vendor/lib/helper-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-client.js","sourceRoot":"","sources":["../../../src/vendor/lib/helper-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,YAAY,EAA0C,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EACL,uBAAuB,GAExB,MAAM,qCAAqC,CAAC;AAqB7C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAS,EACT,EAAE,SAAS,EAAE,MAAM,EAA6D;IAEhF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,SAAS,CACjB,oEAAoE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAChG,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAyC,CAAC;IAC3D,MAAM,cAAc,GAAG,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC;IACxD,yFAAyF;IACzF,MAAM,sBAAsB,GAAG,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;IACjE,MAAM,yBAAyB,GAC7B,sBAAsB,CAAC,CAAC;QACtB,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE;YACvD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YACjC,OAAO,KAAK,KAAK,eAAe,IAAI,KAAK,KAAK,WAAW,CAAC;QAC5D,CAAC,CAAC,CACH;QACH,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,cAAc,GAAoB,YAAY,CAAC;QACnD,yBAAyB;QACzB,cAAc;QACd,EAAE,CAAC,uBAAuB,CAAC,EAAE,MAAM,EAAE;KACtC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,WAAW,CAAC;QACxB,MAAM,EAAE,IAAI;QACZ,SAAS;QACT,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,SAAS;QACtB,cAAc;KACf,CAAM,CAAC;AACV,CAAC"}

package/dist/vendor/lib/middleware.d.ts

@@ -0,0 +1,97 @@
+import type { Middleware } from '../core/middleware';
+import type { PukuBeta } from '../resources/beta/beta';
+import type { BetaFallbackParam, BetaRawMessageDeltaEvent } from '../resources/beta/messages/messages';
+export { BetaFallbackState } from '../internal/request-options';
+/** Why {@link BetaRefusalFallbackOptions.onError} fired. */
+export type BetaRefusalFallbackError = {
+    /** The refusal carries no `fallback_credit_token`, so it can't be retried. */
+    kind: 'no_credit_token';
+    message: string;
+    /** The refusal `message_delta` event, verbatim. */
+    event: BetaRawMessageDeltaEvent;
+} | {
+    /** The stream refused but every fallback entry has been used up. */
+    kind: 'chain_exhausted';
+    message: string;
+    /** The refusal `message_delta` event, verbatim. */
+    event: BetaRawMessageDeltaEvent;
+} | {
+    /** A streaming fallback request failed; the hop was skipped. */
+    kind: 'request_failed';
+    message: string;
+    /** The fallback model whose request failed. */
+    model: string;
+    /** The HTTP status, or `null` when the request threw instead of resolving. */
+    status: number | null;
+    /** The parsed error body, or the thrown error when `status` is `null`. */
+    detail: unknown;
+};
+export interface BetaRefusalFallbackOptions {
+    /**
+     * Betas added to the `puku-beta` header of every `/v1/messages`
+     * request this middleware handles — the original request included, since
+     * refusals only carry a `fallback_credit_token` when the beta is enabled.
+     * Defaults to `['fallback-credit-2026-07-01']`; pass `[]` to send none.
+     */
+    betas?: readonly PukuBeta[] | undefined;
+    /**
+     * Called when a refusal is surfaced to the client rather than retried —
+     * it carries no `fallback_credit_token`, no fallback entries remain, or a
+     * streaming fallback request failed. Discriminate on `error.kind`.
+     * Defaults to logging through the client logger.
+     */
+    onError?: ((error: BetaRefusalFallbackError) => void) | undefined;
+}
+/**
+ * Middleware that retries refused `/v1/messages` requests down a fallback chain.
+ *
+ * Non-streaming: when a response comes back with `stop_reason: 'refusal'`, the
+ * request is retried with each entry of `fallbacks` applied as a patch to the
+ * original params (a set field overrides, an explicit `null` unsets, an absent
+ * field keeps the original value; entries never patch each other's requests)
+ * — passing along the refusal's `fallback_credit_token` — until a model
+ * accepts or the chain is exhausted. A message served by a fallback carries a
+ * `fallback` content block prepended at each model boundary — the same seam
+ * block shape the server-side `fallbacks` param places in `content`, though
+ * the rest of the envelope is the serving hop's as returned (see the
+ * known-divergences note below); an exhausted chain surfaces the final
+ * refusal verbatim.
+ *
+ * Streaming: when the stream ends in `stop_reason: 'refusal'`, a second
+ * request is issued to the fallback model — carrying the refused model's
+ * partial output as a trailing assistant prefill when the refusal grants one
+ * (`fallback_has_prefill_claim`), plus the refusal's `fallback_credit_token`
+ * — and the fallback's events are spliced onto the
+ * still-open stream, so the client sees one continuous message in the
+ * server-side `fallbacks` wire shape: a `fallback` content block at each model
+ * boundary, monotonic block indices, and per-hop `usage.iterations` on the
+ * final `message_delta`. Only `model` is honored from each entry on this path:
+ * the credit token is redeemable only against the refused request's body, so
+ * the other per-entry overrides (`max_tokens`, `thinking`, ...) would be
+ * rejected.
+ *
+ * The fallback-credit beta the credit tokens require is sent by default on
+ * every request the middleware handles; the `betas` option controls this.
+ *
+ * In both modes a fallback that itself refuses with a fresh credit token
+ * continues down the chain. A streaming fallback whose prefill the server
+ * rejects (HTTP 400) is retried once without it; a fallback whose request
+ * fails outright is skipped — its token was never redeemed, so it carries to
+ * the next entry.
+ *
+ * To keep later requests on the model that accepted, pass a
+ * {@link BetaFallbackState} via the `fallbackState` request option; requests
+ * sharing that state start directly at the pinned fallback. Reuse one state
+ * across whatever scope the pin should apply to — typically a conversation.
+ *
+ * @example
+ * ```ts
+ * const client = new PukuAI({
+ *   middleware: [betaRefusalFallbackMiddleware([{ model: 'opus-4.8' }])],
+ * });
+ *
+ * const fallbackState = new BetaFallbackState();
+ * const message = await client.beta.messages.create(params, { fallbackState });
+ * ```
+ */
+export declare function betaRefusalFallbackMiddleware(fallbacks: readonly BetaFallbackParam[], options?: BetaRefusalFallbackOptions): Middleware;