@puku-ai/sdk 4.0.0 → 4.0.2

package/dist/vendor/core/error.d.ts

@@ -0,0 +1,82 @@
+import type { ErrorType } from '../resources/shared';
+/**
+ * Branded base error class for the Puku SDK. Every error the SDK throws
+ * is an instance of `PukuError`, so `err.toString()` and stack traces
+ * report `PukuError: …` consistently.
+ *
+ * `instanceof PukuError` is the canonical check. The class itself is
+ * re-exported from `@puku-ai/sdk` under both `PukuError` and the legacy
+ * `PukuError` name; both refer to the same constructor.
+ */
+export declare class PukuError extends Error {
+    name: string;
+    constructor(message?: string);
+}
+/**
+ * Legacy base-error type alias for source compatibility with code that
+ * imports the SDK's base error type by its old name. Throw sites
+ * should always throw `PukuError` directly; the legacy alias exists only
+ * so consumers' `instanceof` checks keep working across the rename.
+ *
+ * @deprecated Import `PukuError` instead. The alias will be removed in
+ * the next major version.
+ */
+export type LegacyBaseError = PukuError;
+export declare class APIError<TStatus extends number | undefined = number | undefined, THeaders extends Headers | undefined = Headers | undefined, TError extends Object | undefined = Object | undefined> extends PukuError {
+    /** HTTP status for the response that caused the error */
+    readonly status: TStatus;
+    /** HTTP headers for the response that caused the error */
+    readonly headers: THeaders;
+    /** JSON body of the response that caused the error */
+    readonly error: TError;
+    readonly requestID: string | null | undefined;
+    readonly workspaceID: string | null | undefined;
+    /** The `error.type` from the API response body, e.g. `"rate_limit_error"` */
+    readonly type: ErrorType | null;
+    constructor(status: TStatus, error: TError, message: string | undefined, headers: THeaders, type?: ErrorType | null);
+    private static makeMessage;
+    static generate(status: number | undefined, errorResponse: Object | undefined, message: string | undefined, headers: Headers | undefined): APIError;
+}
+export declare class APIUserAbortError extends APIError<undefined, undefined, undefined> {
+    constructor({ message }?: {
+        message?: string;
+    });
+}
+export declare class APIConnectionError extends APIError<undefined, undefined, undefined> {
+    constructor({ message, cause }: {
+        message?: string | undefined;
+        cause?: Error | undefined;
+    });
+}
+export declare class APIConnectionTimeoutError extends APIConnectionError {
+    constructor({ message }?: {
+        message?: string;
+    });
+}
+/**
+ * An error that opts into the SDK's retry policy: throw it (e.g. from
+ * middleware) to have the attempt retried.
+ *
+ * Note that the request will only be retried when `maxRetries` has not been exhausted.
+ */
+export declare class RetryableError extends PukuError {
+    constructor(message?: string, { cause }?: {
+        cause?: unknown;
+    });
+}
+export declare class BadRequestError extends APIError<400, Headers> {
+}
+export declare class AuthenticationError extends APIError<401, Headers> {
+}
+export declare class PermissionDeniedError extends APIError<403, Headers> {
+}
+export declare class NotFoundError extends APIError<404, Headers> {
+}
+export declare class ConflictError extends APIError<409, Headers> {
+}
+export declare class UnprocessableEntityError extends APIError<422, Headers> {
+}
+export declare class RateLimitError extends APIError<429, Headers> {
+}
+export declare class InternalServerError extends APIError<number, Headers> {
+}

package/dist/vendor/core/error.js

@@ -0,0 +1,140 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { castToError } from '../internal/errors.js';
+/**
+ * Branded base error class for the Puku SDK. Every error the SDK throws
+ * is an instance of `PukuError`, so `err.toString()` and stack traces
+ * report `PukuError: …` consistently.
+ *
+ * `instanceof PukuError` is the canonical check. The class itself is
+ * re-exported from `@puku-ai/sdk` under both `PukuError` and the legacy
+ * `PukuError` name; both refer to the same constructor.
+ */
+export class PukuError extends Error {
+    name = 'PukuError';
+    constructor(message) {
+        super(message);
+        this.name = 'PukuError';
+    }
+}
+export class APIError extends PukuError {
+    /** HTTP status for the response that caused the error */
+    status;
+    /** HTTP headers for the response that caused the error */
+    headers;
+    /** JSON body of the response that caused the error */
+    error;
+    requestID;
+    workspaceID;
+    /** The `error.type` from the API response body, e.g. `"rate_limit_error"` */
+    type;
+    constructor(status, error, message, headers, type) {
+        super(`${APIError.makeMessage(status, error, message)}`);
+        this.status = status;
+        this.headers = headers;
+        this.requestID = headers?.get('request-id');
+        this.workspaceID = headers?.get('puku-workspace-id');
+        this.error = error;
+        this.type = type ?? null;
+    }
+    static makeMessage(status, error, message) {
+        const msg = error?.message ?
+            typeof error.message === 'string' ?
+                error.message
+                : JSON.stringify(error.message)
+            : error ? JSON.stringify(error)
+                : message;
+        if (status && msg) {
+            return `${status} ${msg}`;
+        }
+        if (status) {
+            return `${status} status code (no body)`;
+        }
+        if (msg) {
+            return msg;
+        }
+        return '(no status code or body)';
+    }
+    static generate(status, errorResponse, message, headers) {
+        if (!status || !headers) {
+            return new APIConnectionError({ message, cause: castToError(errorResponse) });
+        }
+        const error = errorResponse;
+        const type = error?.['error']?.['type'];
+        if (status === 400) {
+            return new BadRequestError(status, error, message, headers, type);
+        }
+        if (status === 401) {
+            return new AuthenticationError(status, error, message, headers, type);
+        }
+        if (status === 403) {
+            return new PermissionDeniedError(status, error, message, headers, type);
+        }
+        if (status === 404) {
+            return new NotFoundError(status, error, message, headers, type);
+        }
+        if (status === 409) {
+            return new ConflictError(status, error, message, headers, type);
+        }
+        if (status === 422) {
+            return new UnprocessableEntityError(status, error, message, headers, type);
+        }
+        if (status === 429) {
+            return new RateLimitError(status, error, message, headers, type);
+        }
+        if (status >= 500) {
+            return new InternalServerError(status, error, message, headers, type);
+        }
+        return new APIError(status, error, message, headers, type);
+    }
+}
+export class APIUserAbortError extends APIError {
+    constructor({ message } = {}) {
+        super(undefined, undefined, message || 'Request was aborted.', undefined);
+    }
+}
+export class APIConnectionError extends APIError {
+    constructor({ message, cause }) {
+        super(undefined, undefined, message || 'Connection error.', undefined);
+        // in some environments the 'cause' property is already declared
+        // @ts-ignore
+        if (cause)
+            this.cause = cause;
+    }
+}
+export class APIConnectionTimeoutError extends APIConnectionError {
+    constructor({ message } = {}) {
+        super({ message: message ?? 'Request timed out.' });
+    }
+}
+/**
+ * An error that opts into the SDK's retry policy: throw it (e.g. from
+ * middleware) to have the attempt retried.
+ *
+ * Note that the request will only be retried when `maxRetries` has not been exhausted.
+ */
+export class RetryableError extends PukuError {
+    constructor(message, { cause } = {}) {
+        super(message ?? 'Retryable error.');
+        // in some environments the 'cause' property is already declared
+        // @ts-ignore
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+export class BadRequestError extends APIError {
+}
+export class AuthenticationError extends APIError {
+}
+export class PermissionDeniedError extends APIError {
+}
+export class NotFoundError extends APIError {
+}
+export class ConflictError extends APIError {
+}
+export class UnprocessableEntityError extends APIError {
+}
+export class RateLimitError extends APIError {
+}
+export class InternalServerError extends APIError {
+}
+//# sourceMappingURL=error.js.map

package/dist/vendor/core/error.js.map

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

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

@@ -0,0 +1,153 @@
+import type { BasePuku } from '../client';
+import type { Fetch } from '../internal/builtin-types';
+import type { FinalRequestOptions } from '../internal/request-options';
+import { type Logger } from '../internal/utils/log';
+import type { APIRequest } from './api';
+/**
+ * Invokes the rest of the middleware chain, ending with the underlying `fetch`.
+ *
+ * This function can be invoked multiple times.
+ */
+export type MiddlewareNext = (request: APIRequest) => Promise<Response>;
+/**
+ * Helpers passed to each middleware alongside `next`, scoped to the request
+ * in flight (one context is shared by every middleware in the chain).
+ */
+export interface MiddlewareContext {
+    /**
+     * The SDK request options the API call in flight was made with: `method`,
+     * `path`, the pre-encoded `body`, `stream`, etc.
+     *
+     * `undefined` when the chain isn't running for an SDK API request, i.e.
+     * for credential token-exchange requests.
+     */
+    readonly options?: FinalRequestOptions | undefined;
+    /**
+     * The client's logger, pre-filtered to the client's configured log level
+     * (the `logLevel` client option or the `PUKU_LOG` environment
+     * variable). Calls below the active level are no-ops, so it's always safe
+     * to call; with no logger configured it writes to the global `console`.
+     *
+     * Values are logged as-is — when logging request or response headers,
+     * redact credentials (`authorization`, `x-api-key`, `cookie`) the way the
+     * SDK's own logs do.
+     *
+     * @example
+     * ```ts
+     * const mw: Middleware = async (request, next, ctx) => {
+     *   ctx.logger.debug('->', request.method, request.url);
+     *   return next(request);
+     * };
+     * ```
+     */
+    readonly logger: Logger;
+    /**
+     * Parse a response body the way the SDK would for the request in flight:
+     *
+     * - JSON responses are decoded, with the non-enumerable `_request_id`
+     *   property attached like SDK return values, and anything else resolves
+     *   to the body text.
+     * - For streaming requests ({@link options}`.stream`), resolves immediately
+     *   with a {@link Stream} reading an independent copy of the response body —
+     *   iterating it doesn't consume the client's events, and aborting or
+     *   `break`ing out of it doesn't cancel the underlying request. Each call
+     *   returns a fresh `Stream` (streams are single-consumer, so they aren't
+     *   cached). Error (non-2xx) responses parse as JSON/text rather than as a
+     *   stream, mirroring the SDK's own handling.
+     * - For binary requests, resolves with the `Response` itself, unconsumed.
+     *
+     * Reads through an internal `response.clone()`, so the response stays
+     * readable: the client (and any other middleware) can still consume the
+     * body afterwards. Non-stream results are cached per `Response` and shared
+     * across the middleware chain, so repeated calls cost a single read.
+     *
+     * @example
+     * ```ts
+     * const mw: Middleware = async (request, next, ctx) => {
+     *   const response = await next(request);
+     *   const data = await ctx.parse<Message>(response);
+     *   if (data.type === 'message') console.log(data.usage);
+     *   return response;
+     * };
+     * ```
+     */
+    parse<T = unknown>(response: Response): Promise<T>;
+}
+/**
+ * A function that wraps each HTTP request made by the client.
+ *
+ * Middleware may observe or modify the request before calling `next`, observe
+ * or replace the response, short-circuit by returning a `Response` without
+ * calling `next`, or call `next` multiple times to implement custom retries.
+ *
+ * Middleware always observes the canonical PukuAI-shaped request — e.g.
+ * `POST .../v1/messages` with `model` and `stream` in the JSON body and
+ * `puku-beta` as a header — with the client's logical credentials
+ * (`x-api-key` / `Authorization`) applied. On clients for third-party
+ * backends (Bedrock, Vertex, Foundry), the backend adaptation — URL and body
+ * rewriting, request signing (e.g. AWS SigV4), and response normalization
+ * (e.g. AWS EventStream to SSE) — runs *inside* `next`, so middleware behaves
+ * identically on every backend: mutating the request is safe (signing covers
+ * the final body), and streaming responses are observed as SSE. Each `next()`
+ * call re-runs the adaptation, so custom retries re-sign from scratch. To
+ * observe the literal wire traffic instead, provide a custom `fetch`.
+ *
+ * Middleware must not consume the body of the `Response` it returns - the
+ * client still needs to read it. To inspect the body, use
+ * `await ctx.parse(response)` (cached, leaves the body readable) or read a
+ * clone (`await response.clone().text()`); to transform it, return a
+ * replacement, e.g. `new Response(body, response)`.
+ *
+ * Middleware runs per HTTP attempt, inside the SDK's retry loop; the attempt
+ * number is available via the `X-Stainless-Retry-Count` request header. An
+ * error thrown from middleware propagates to the caller as-is.
+ *
+ * Middleware errors are **not** retried apart from connection-level errors:
+ * timeout/abort errors, errors thrown by `fetch()`, and `APIConnectionError`s
+ * or `RetryableError`s — thrown directly or present anywhere in an error's
+ * `cause` chain. Retryable middleware errors still propagate to the caller
+ * as-is once retries are exhausted.
+ *
+ * @example
+ * ```ts
+ * const logger: Middleware = async (request, next, ctx) => {
+ *   ctx.logger.debug('->', request.method, request.url);
+ *   const response = await next(request);
+ *   ctx.logger.debug('<-', response.status, request.url);
+ *   return response;
+ * };
+ *
+ * const client = new PukuAI({ middleware: [logger] });
+ * ```
+ */
+export type Middleware = (request: APIRequest, next: MiddlewareNext, ctx: MiddlewareContext) => Promise<Response>;
+/** Whether `err` was thrown by the underlying `fetch` rather than by a middleware. */
+export declare function isFetchOriginError(err: unknown): boolean;
+/**
+ * Whether an error thrown by middleware should stay on the SDK's
+ * connection-error retry policy: fetch-origin, abort, `APIConnectionError`, or
+ * `RetryableError` — checked through the error's `cause` chain.
+ */
+export declare function isRetryableError(err: unknown): boolean;
+/**
+ * Wraps `fetchFn` so each call runs through `middleware`, keeping the same
+ * call signature as `fetch` itself.
+ *
+ * With no middleware, calls are passed straight through to `fetchFn`.
+ * Otherwise the arguments are normalized into an {@link APIRequest} (headers
+ * coerced to a `Headers` instance, URL stringified) before entering the
+ * chain. The chain is composed per call, so mutations of a `middleware`
+ * array are picked up by later requests.
+ *
+ * `options` — the SDK request options behind this call, when there are any —
+ * is surfaced to middleware as `ctx.options` and drives `ctx.parse`.
+ *
+ * `client` supplies `ctx.logger` (the client's level-filtered logger);
+ * without it, `ctx.logger` falls back to the client defaults: `console`,
+ * filtered to `PUKU_LOG` or `'warn'`.
+ */
+export declare function wrapFetchWithMiddleware(fetchFn: Fetch, middleware: readonly Middleware[], options?: FinalRequestOptions | undefined, client?: BasePuku | undefined): Fetch;
+/**
+ * Composes `middleware` around `fetchFn` and returns the entry point of the chain.
+ */
+export declare function applyMiddleware(fetchFn: Fetch, middleware: readonly Middleware[], options?: FinalRequestOptions | undefined, client?: BasePuku | undefined): MiddlewareNext;

package/dist/vendor/core/middleware.js

@@ -0,0 +1,168 @@
+import { castToError, isAbortError } from '../internal/errors.js';
+import { addResponseIDs } from '../internal/parse.js';
+import { defaultLogger, loggerFor } from '../internal/utils/log.js';
+import { PukuError, APIConnectionError, RetryableError } from './error.js';
+import { Stream } from './streaming.js';
+/**
+ * Errors thrown by the underlying `fetch`, as opposed to by a middleware.
+ *
+ * Tracked so the client can apply its connection-error retry policy to
+ * transport failures while letting errors thrown by middleware propagate to
+ * the caller untouched.
+ */
+const fetchOriginErrors = new WeakSet();
+/** Whether `err` was thrown by the underlying `fetch` rather than by a middleware. */
+export function isFetchOriginError(err) {
+    return typeof err === 'object' && err !== null && fetchOriginErrors.has(err);
+}
+/**
+ * Whether an error thrown by middleware should stay on the SDK's
+ * connection-error retry policy: fetch-origin, abort, `APIConnectionError`, or
+ * `RetryableError` — checked through the error's `cause` chain.
+ */
+export function isRetryableError(err) {
+    const seen = new Set(); // guard against `cause` cycles
+    while (typeof err === 'object' && err !== null && !seen.has(err)) {
+        seen.add(err);
+        if (isFetchOriginError(err) ||
+            isAbortError(err) ||
+            err instanceof APIConnectionError ||
+            err instanceof RetryableError) {
+            return true;
+        }
+        err = err.cause;
+    }
+    return false;
+}
+/**
+ * Wraps `fetchFn` so each call runs through `middleware`, keeping the same
+ * call signature as `fetch` itself.
+ *
+ * With no middleware, calls are passed straight through to `fetchFn`.
+ * Otherwise the arguments are normalized into an {@link APIRequest} (headers
+ * coerced to a `Headers` instance, URL stringified) before entering the
+ * chain. The chain is composed per call, so mutations of a `middleware`
+ * array are picked up by later requests.
+ *
+ * `options` — the SDK request options behind this call, when there are any —
+ * is surfaced to middleware as `ctx.options` and drives `ctx.parse`.
+ *
+ * `client` supplies `ctx.logger` (the client's level-filtered logger);
+ * without it, `ctx.logger` falls back to the client defaults: `console`,
+ * filtered to `PUKU_LOG` or `'warn'`.
+ */
+export function wrapFetchWithMiddleware(fetchFn, middleware, options, client) {
+    return async (url, init = {}) => {
+        if (middleware.length === 0) {
+            // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
+            return fetchFn.call(undefined, url, init);
+        }
+        const headers = init.headers instanceof Headers ? init.headers : new Headers(init.headers);
+        const response = await applyMiddleware(fetchFn, middleware, options, client)({
+            ...init,
+            headers,
+            url: typeof url === 'string' ? url
+                : url instanceof URL ? url.href
+                    : url.url,
+        });
+        // Catch a footgun before the client tries to read the body itself and
+        // fails with a confusing low-level stream error.
+        if (response.bodyUsed || response.body?.locked) {
+            throw new PukuError('middleware consumed the response body; use response.clone() to inspect it, ' +
+                'or return new Response(body, response) to consume and replace it');
+        }
+        return response;
+    };
+}
+/**
+ * Creates the {@link MiddlewareContext} shared by every middleware in one chain.
+ */
+function createMiddlewareContext(options, client) {
+    // Keyed on the Response so each `next()` call's response (e.g. with custom
+    // retries, or a middleware swapping in a replacement) parses independently,
+    // while several middleware parsing the same response share a single read.
+    const cache = new WeakMap();
+    return {
+        options,
+        // Resolved per chain, so changes to the client's `logLevel`/`logger`
+        // apply to subsequent requests.
+        logger: client ? loggerFor(client) : defaultLogger(),
+        parse(response) {
+            // Streams are single-consumer, so caching one would hand later callers
+            // an already-consumed stream; every call gets a fresh clone-backed one.
+            if (options?.stream && response.ok) {
+                return parseMiddlewareResponse(response, options, client);
+            }
+            let parsed = cache.get(response);
+            if (!parsed) {
+                parsed = parseMiddlewareResponse(response, options, client);
+                cache.set(response, parsed);
+            }
+            return parsed;
+        },
+    };
+}
+/**
+ * Mirrors the client's own response parsing (`defaultParseResponse` in
+ * `internal/parse.ts`), reading through a clone so the body stays available
+ * to the rest of the chain and the client itself.
+ */
+async function parseMiddlewareResponse(response, options, client) {
+    if (response.bodyUsed || response.body?.locked) {
+        throw new PukuError('cannot ctx.parse() a response whose body was already consumed; ' +
+            'call ctx.parse() instead of reading the body, or read via response.clone()');
+    }
+    // Error responses parse as JSON/text below — the SDK only stream-parses
+    // successful responses, and middleware typically wants the error body.
+    if (options?.stream && response.ok) {
+        // A fresh controller rather than the request's own: aborting (or
+        // `break`ing out of) the middleware's stream must not cancel the
+        // in-flight request the client is still reading.
+        return Stream.fromSSEResponse(response.clone(), new AbortController(), client);
+    }
+    // fetch refuses to read the body when the status code is 204.
+    if (response.status === 204) {
+        return null;
+    }
+    if (options?.__binaryResponse) {
+        return response;
+    }
+    const contentType = response.headers.get('content-type');
+    const mediaType = contentType?.split(';')[0]?.trim();
+    const isJSON = mediaType?.includes('application/json') || mediaType?.endsWith('+json');
+    if (isJSON) {
+        if (response.headers.get('content-length') === '0') {
+            // if there is no content we can't do anything
+            return undefined;
+        }
+        return addResponseIDs(await response.clone().json(), response);
+    }
+    return await response.clone().text();
+}
+/**
+ * Composes `middleware` around `fetchFn` and returns the entry point of the chain.
+ */
+export function applyMiddleware(fetchFn, middleware, options, client) {
+    // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
+    let next = async ({ url, ...init }) => {
+        try {
+            return await fetchFn.call(undefined, url, init);
+        }
+        catch (err) {
+            // Brand the error as fetch-origin, normalizing with `castToError` first since a
+            // WeakSet can't hold primitives and the brand must be on the same object the
+            // client's own `castToError` will later pass through.
+            const error = castToError(err);
+            fetchOriginErrors.add(error);
+            throw error;
+        }
+    };
+    const ctx = createMiddlewareContext(options, client);
+    for (let i = middleware.length - 1; i >= 0; i--) {
+        const mw = middleware[i];
+        const nextInner = next;
+        next = async (request) => mw(request, nextInner, ctx);
+    }
+    return next;
+}
+//# sourceMappingURL=middleware.js.map

package/dist/vendor/core/middleware.js.map

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